home *** CD-ROM | disk | FTP | other *** search
/ Over 1,000 Windows 95 Programs / Over 1000 Windows 95 Programs (Microforum) (Disc 1).iso / 1263 / sxt.doc < prev    next >
Text File  |  1997-04-18  |  224KB  |  4,698 lines
  1.  
  2.  
  3.  
  4.  
  5.                        SXT (TM) SOFTWARE EXPLORATION TOOLS
  6.  
  7.  
  8.  
  9.                            CXT (TM) C EXPLORATION TOOLS
  10.                         CFT (TM) C FUNCTION TREE GENERATOR
  11.                        CST (TM) C STRUCTURE TREE GENERATOR
  12.  
  13.  
  14.                          DXT (TM) DBASE EXPLORATION TOOLS
  15.                       DFT (TM) DBASE FUNCTION TREE GENERATOR
  16.  
  17.  
  18.                         FXT (TM) FORTRAN EXPLORATION TOOLS
  19.                      FFT (TM) FORTRAN FUNCTION TREE GENERATOR
  20.  
  21.  
  22.                          LXT (TM) LISP EXPLORATION TOOLS
  23.                       LFT (TM) LISP FUNCTION TREE GENERATOR
  24.  
  25.  
  26.  
  27.  
  28.                             SXT command line versions
  29.                              SXTWIN Windows versions
  30.  
  31.  
  32.  
  33.                                    August 1996
  34.  
  35.                  Copyright (C) Juergen Mueller (J.M.) 1988-1996.
  36.                          All Rights Reserved World-Wide.
  37.  
  38.  
  39.  
  40.          DISCLAIMER OF WARRANTY
  41.  
  42.          THIS  SOFTWARE  AND  ACCOMPANYING  WRITTEN  MATERIAL (INCLUDING
  43.          INSTRUCTIONS FOR USE) IS PROVIDED "AS IS" WITH NO WARRANTIES OF
  44.          ANY  KIND,   EITHER  EXPRESS  OR  IMPLIED,  INCLUDING,  WITHOUT
  45.          LIMITATION,  THE  WARRANTIES  OF  DESIGN,  MERCHANTIBILITY  AND
  46.          FITNESS  FOR A PARTICULAR PURPOSE,  NONINFRINGEMENT, OR ARISING
  47.          FROM  A COURSE OF DEALING, USAGE OR  TRADE PRACTICE. THE ENTIRE
  48.          RISK AS  TO THE RESULTS AND PERFORMANCE OF THE SOFTWARE IS WITH
  49.          YOU.
  50.  
  51.          THE  AUTHOR AND COPYRIGHT  HOLDER SHALL HAVE  NO LIABILITY WITH
  52.          RESPECT TO THE INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY
  53.          PATENTS BY THIS SOFTWARE OR ANY PART THEREOF.
  54.  
  55.          IN NO  EVENT WILL THE AUTHOR AND COPYRIGHT HOLDER BE LIABLE FOR
  56.          DAMAGES,  INCLUDING  ANY LOST  PROFITS, LOST  MONIES,  OR OTHER
  57.          DIRECT,  INDIRECT, GENERAL,  SPECIAL, INCIDENTAL,  EXEMPLARY OR
  58.          CONSEQUENTIAL  DAMAGES ARISING  IN ANY  WAY OUT  OF THE  USE OR
  59.          INABILITY  TO USE THIS PROGRAM (INCLUDING,  BUT NOT LIMITED TO,
  60.          PROCUREMENT   OF   SUBSTITUTE  GOODS   OR   SERVICES,  BUSINESS
  61.          INTERRUPTION, LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR
  62.          LOSSES  SUSTAINED BY YOU OR  THIRD PARTIES OR A  FAILURE OF THE
  63.          PROGRAM  TO OPERATE WITH ANY OTHER PROGRAMS)  AND ON ANY THEORY
  64.          OF  LIABILITY,  EVEN  IF ADVISED  OF  THE  POSSIBILITY  OF SUCH
  65.          DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY.
  66.  
  67.  
  68.          ACKNOWLEDGEMENT
  69.  
  70.          BY USING  THIS SOFTWARE YOU ACKNOWLEDGE THAT YOU HAVE READ THIS
  71.          LIMITED  WARRANTY AND ACCOMPANYING REMARKS,  UNDERSTAND IT, AND
  72.          AGREE  TO BE BOUND BY ITS TERMS  AND CONDITIONS. YOU ALSO AGREE
  73.          THAT THIS  IS THE COMPLETE AND EXCLUSIVE STATEMENT OF AGREEMENT
  74.          BETWEEN  THE  PARTIES  AND  SUPERSEDE  ALL  PROPOSALS OR  PRIOR
  75.          AGREEMENTS,  ORAL  OR  WRITTEN,  AND  ANY OTHER  COMMUNICATIONS
  76.          BETWEEN  THE  PARTIES RELATING  TO  THE SUBJECT  MATTER  OF THE
  77.          LIMITED  WARRANTY. YOU  AGREE THAT THIS  NOTICE APPLIES  TO ALL
  78.          FILES IN THIS SOFTWARE DISTRIBUTION.
  79.  
  80.  
  81.          You  are  expressly prohibited  from selling  this  software or
  82.          parts  of it  in any form,  circulate it  in any  incomplete or
  83.          modified  form, distribute it  with another  product (except as
  84.          Shareware) or  removing this notice. No one may modify or patch
  85.          any  of the  executable files  in any  way, including,  but not
  86.          limited  to,  decompiling, disassembling  or  otherwise reverse
  87.          engineering this software in whole or part.
  88.  
  89.          The documentation  may be distributed verbatim, but changing is
  90.          not  allowed.   The  information  and  specifications  in  this
  91.          document are subject to change without notice.
  92.  
  93.          THIS  VERSION  OF  THE  DOCUMENTATION,  SOFTWARE AND  COPYRIGHT
  94.          SUPERSEDES ALL PREVIOUS VERSIONS. THIS SOFTWARE AND ITS RELATED
  95.          DOCUMENTATION MAY CHANGE WITHOUT NOTICE.
  96.  
  97.  
  98.  
  99.                                         2
  100.  
  101.  
  102.  
  103.          This software and documentation is Copyright (C) 1988-1996 by
  104.  
  105.               Juergen Mueller
  106.               Aldingerstrasse 22
  107.               D-70806 Kornwestheim
  108.               GERMANY
  109.  
  110.               Email address: juergen.mueller@isw.uni-stuttgart.de
  111.  
  112.  
  113.          THERE ARE  NO AND HAVE NEVER BEEN RELATIONS BETWEEN THE AUTHORS
  114.          PROFESSIONAL  WORK AND THE SXT DEVELOPMENT.  THE SXT PROJECT IS
  115.          AND HAS  EVER BEEN AN INDEPENDENT PRIVATE PROJECT OF THE AUTHOR
  116.          AND IS WRITTEN AND MAINTAINED IN HIS FREE TIME.
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.                                         3
  163.  
  164.  
  165.  
  166.          LICENSE
  167.  
  168.          This  software is not  public domain  or free  software, but is
  169.          being  distributed as shareware.  It is  protected by copyright
  170.          and distributed under this license restricting its use.
  171.  
  172.          Non-registered  users of  this software  are granted  a limited
  173.          license for a 30-day evaluation period starting from the day of
  174.          the first  use to make an evaluation copy for trial use for the
  175.          express  purpose   of  determining  whether  this  software  is
  176.          suitable  for their needs. At the end  of this trial period you
  177.          should  either  register your  copy or  discontinue  using this
  178.          software.  The  use of  unregistered copies  of  this software,
  179.          outside  of the initial 30-day trial,  by any person, business,
  180.          corporation, government  agency or any other entity is strictly
  181.          prohibited.
  182.  
  183.          This  means that if you use this  software, then you should pay
  184.          for  your copy.  This software is  not free,  but you  have the
  185.          opportunity to  try it before you buy it. Either pay for it, or
  186.          quit using  it. A registration entitles you to use your copy of
  187.          this  software on any  and all  computers available  to you. If
  188.          other  people have access to this software  or may use it, then
  189.          additional copies or a site license should be purchased.
  190.  
  191.          All  users are granted a limited license  to copy this software
  192.          only  for the  trial use  of others  and  subject to  the above
  193.          limitations.   This  license  does  not  include  distribution,
  194.          selling or  copying of this software package in connection with
  195.          any  other  product  or  service  or  for  distribution in  any
  196.          incomplete  or modified form. Operators  of electronic bulletin
  197.          board systems  and software servers (like Internet FTP-Servers)
  198.          are  encouraged to post this software  for downloading by their
  199.          users, as long as the above conditions are met.
  200.  
  201.          This  package is expected  to be distributed  as shareware, but
  202.          the  fees  paid  for "distribution"  costs  (disk,  CD-ROM) are
  203.          strictly  exchanged between the distributor  and the recipient,
  204.          and the author makes no express or implied warranties about the
  205.          quality  or  integrity  of  such  indirectly  acquired  copies.
  206.          Distributors and users may obtain the package directly from the
  207.          author  by following  the ordering  procedures in  the REGISTER
  208.          files.
  209.  
  210.  
  211.          REGISTRATION REMINDER
  212.  
  213.          Unregistered copies of this software are 100% fully functional.
  214.          I make them this  way so that you can have a real look at them,
  215.          and  then decide whether they fit your  needs or not. This work
  216.          depends on your honesty. If you use it, I expect you to pay for
  217.          it.  When you pay  for the shareware  you like,  you are voting
  218.          with your pocketbook, and will encourage me and other shareware
  219.          authors to develop more of these kinds of products.
  220.          THANK YOU FOR SUPPORTING THE SHAREWARE CONCEPT
  221.  
  222.  
  223.  
  224.  
  225.                                         4
  226.  
  227.  
  228.  
  229.          TABLE OF CONTENTS
  230.  
  231.          1 THE SXT SOFTWARE EXPLORATION TOOLS                          6
  232.          2 INTRODUCTION                                                7
  233.          3 PROGRAM DESCRIPTION                                         9
  234.          4 LANGUAGE IMPLEMENTATION                                    11
  235.          4.1 C-LANGUAGE IMPLEMENTATION AND C-PREPROCESSOR             11
  236.          4.2 C++ LANGUAGE IMPLEMENTATION                              13
  237.          4.3 DBASE SOURCE CODE                                        13
  238.          4.4 FORTRAN SOURCE CODE                                      14
  239.          4.5 LISP SOURCE CODE                                         15
  240.          4.6 ASSEMBLER SOURCE CODE                                    15
  241.          5 DATABASE GENERATION                                        16
  242.          6 PROGRAM LIMITATIONS                                        17
  243.          7 SXT OPTIONS                                                20
  244.          8 MISCELLANEOUS                                              45
  245.          8.1 OUTPUT DESCRIPTION                                       45
  246.          8.1.1 CFT OUTPUT                                             45
  247.          8.1.2 CST OUTPUT                                             46
  248.          8.1.3 OUTPUT INTERPRETATION                                  47
  249.          8.2 TOOLS FOR DATABASE PROCESSING                            47
  250.          8.3 INTEGRATION INTO PROGRAM DEVELOPMENT ENVIRONMENTS        57
  251.          8.4 IMPROVING EXECUTION SPEED                                58
  252.          8.5 PROBLEMS                                                 59
  253.          8.5.1 FREQUENTLY ASKED QUESTIONS (FAQ)                       59
  254.          8.5.2 TROUBLE SHOOTING                                       60
  255.          8.6 REFERENCES                                               63
  256.          8.7 TRADEMARKS                                               65
  257.          9 APPENDIX                                                   66
  258.          9.1 APPENDIX 1: C/C++ PRECOMPILER DEFINES                    66
  259.          9.2 APPENDIX 2: RESERVED C/C++ KEYWORDS                      68
  260.          9.3 APPENDIX 3: RESERVED FORTRAN KEYWORDS                    69
  261.          9.4 APPENDIX 4: EFFICIENCY                                   70
  262.          9.5 APPENDIX 5: SYSTEM REQUIREMENTS                          72
  263.          9.6 APPENDIX 6: INSTALLATION                                 72
  264.          9.7 APPENDIX 7: SXT REVIEWS                                  73
  265.          9.8 APPENDIX 8: AVAILABILITY                                 73
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.                                         5
  289.  
  290.  
  291.  
  292.          1   THE SXT SOFTWARE EXPLORATION TOOLS
  293.  
  294.          The SXT Software Exploration Tools are a collection of software
  295.          analysis tools  providing a similar functionality for different
  296.          programming languages.
  297.  
  298.          The following packages are available:
  299.  
  300.          CXT - C Exploration Tools:
  301.            CFT - C Function Tree Generator
  302.            Tool  to analyze and display  the function call relationships
  303.            within the source code of C programs.
  304.            CST - C Structure Tree Generator
  305.            Tool to analyze and display the structure/class relationships
  306.            within the source code of C programs.
  307.  
  308.          DXT - DBASE Exploration Tools:
  309.            DFT - DBASE Function Tree Generator
  310.            Tool  to analyze and display  the function call relationships
  311.            within the source code of DBASE, CLIPPER '87 and other XBASE-
  312.            like programs.
  313.  
  314.          FXT - FORTRAN Exploration Tools:
  315.            FFT - FORTRAN Function Tree Generator
  316.            Tool  to analyze and display  the function call relationships
  317.            within the source code of FORTRAN programs.
  318.  
  319.          LXT - LISP Exploration Tools:
  320.            LFT - LISP Function Tree Generator
  321.            Tool  to analyze and display  the function call relationships
  322.            within the source code of LISP and SCHEME programs.
  323.  
  324.          Each  of  these  packages  consists  of  the  analysis  program
  325.          ("Analyzer") and a recall program ("Navigator") to retrieve the
  326.          analysis  results  which  can be  stored  in  a  database, plus
  327.          documentation  and additional  macros to integrate  these tools
  328.          into popular editors like BRIEF, QEDIT or MicroEMACS.
  329.  
  330.          Each of these packages is available for the following systems:
  331.  
  332.          SXT command line text mode versions:
  333.          * DOS real mode                             (shareware release)
  334.          * DOS 386 protected mode                    (registered users)
  335.          * Windows 32 bit (command line text mode)   (registered users)
  336.          * OS/2 (command line text mode)             (registered users)
  337.  
  338.          SXTWIN Windows versions:
  339.          * Windows 16 bit (Windows 3.1/3.11)         (shareware release)
  340.          * Windows 32 bit (Windows NT, Windows 95, Win32s) (registered
  341.          users)
  342.  
  343.          There  are  no  differences in  the  functionality  between the
  344.          versions for the different systems.
  345.  
  346.          The  author has  no plans  to port  the  SXT programs  to other
  347.          platforms or operating systems like Apple MacIntosh, UNIX (SCO,
  348.          Solaris,  AIX, HP-UX, Linux,  ...), Atari or  Amiga. The source
  349.          code of the SXT programs is not available.
  350.  
  351.                                         6
  352.  
  353.  
  354.  
  355.  
  356.  
  357.          IMPORTANT NOTICE ABOUT THIS DOCUMENT
  358.  
  359.          Although  this document is mainly based  on the description for
  360.          the CXT programs CFT and CST (which were up to version 2.13 the
  361.          only  public available SXT  programs) and  therefore very C/C++
  362.          related,  the description applies in the same  way to all other
  363.          SXT packages. The names CXT/CXTWIN resp. CFT/CST, CFTN/CSTN and
  364.          CFTWIN/CSTWIN  can  be simply  exchanged by  the  similar other
  365.          product names DXT/DFT, FXT/FFT or LXT/LFT. Where necessary, the
  366.          specific  differences   of  the  SXT  packages  are  described,
  367.          especially  in the chapter  about the  options. I  have done it
  368.          this way  to ensure an overall consistency, to keep all related
  369.          things  together  and to  reduce  the efforts  for  writing and
  370.          maintaining this document.
  371.  
  372.  
  373.          2   INTRODUCTION
  374.  
  375.          The SXT  programs are powerful program development, maintenance
  376.          and  documentation  tools.  They  are  primarily  intended  for
  377.          analyzing  large  programs,  where  it  is  difficult,  if  not
  378.          impossible,  for the  programmer to find  the structure  of the
  379.          whole  program. They allow the  analysis of the  source code of
  380.          applications,  no matter how big  or complex they  are. The SXT
  381.          programs  are also very  useful to explore  unknown source code
  382.          and to  get complete overview about its internal structure. The
  383.          re-engineering  of old and/or undocumented  source code becomes
  384.          much easier  with these programs. The tools help the programmer
  385.          to  analyze, identify, locate and  access all parts  of a large
  386.          software  system. They are designed  to support software reuse,
  387.          maintenance and reliability.
  388.  
  389.          By  preprocessing, scanning  and  analyzing the  entire program
  390.          source code  as a single unit, these programs build an internal
  391.          representation  of the function call  hierarchy (CFT, DFT, FFT,
  392.          LFT)  and of the data structure  relations (CST). The resulting
  393.          output  shows from  a global perspective  the interdependencies
  394.          and hierarchical  structure between the functions or data types
  395.          of  the whole, multi  file, software  project. Several features
  396.          and options allow the user to customize the generated hierarchy
  397.          call  tree output and to get a  large set of useful information
  398.          about the source code. The hierarchy structure is always up-to-
  399.          date  because  it relies  on the  original source  code  as the
  400.          primary  source of information.  Written software documentation
  401.          often  differs from  that what  really has  been coded,  so the
  402.          source code itself is the ultimate documentation. The resulting
  403.          output files  can be used for various purposes like development
  404.          or documentation. For registered users there are no restriction
  405.          limits in using them for their own work.
  406.  
  407.          The  output with  the call  tree and  the other  information is
  408.          written in  ASCII format. Information about the functions, data
  409.          types and files can also be written as formatted text files and
  410.          used  as  input  for other  programs  like  word  processors or
  411.          spreadsheet calculators. The programs can additionally generate
  412.          the output in HTML (HyperText Markup Language) format which can
  413.  
  414.                                         7
  415.  
  416.  
  417.  
  418.          be viewed  by WWW (World Wide Web) browsers like Netscape, NCSA
  419.          Mosaic or Microsoft Internet Explorer (see option -HTML) and in
  420.          RTF  (Rich Text Format)  format which  can be  imported by word
  421.          processors. The  RTF output can be used to compile Windows help
  422.          files  with the Windows Help Compiler which  can be viewed with
  423.          WinHelp (see option -RTF).
  424.  
  425.          Displaying  and  printing  a  graphical  representation of  the
  426.          analysis results  as a call graph is not directly supported bye
  427.          the  SXT  programs  but owners  of  RATIONAL  ROSE,  a powerful
  428.          software  development case  tool  supporting the  Booch Object-
  429.          Oriented Analysis and Design (OOAD) method, can (mis-) use this
  430.          tool   for  such  purposes.  The   SXT  programs  can  generate
  431.          compatible output  which can be imported by Rational Rose. (see
  432.          option -RATIONAL for a detailed description).
  433.  
  434.          An important  feature is the database generation. It allows the
  435.          recalling of  information without reprocessing the source code.
  436.          The  database  can again  be read  by  CFT and  CST  to produce
  437.          different outputs  or to add new files. Special recall programs
  438.          (CFTN and CSTN) allow fast searching for items in the database.
  439.          These programs  can be used within any environment, for example
  440.          on  the DOS  command line  or from  inside editors  like BRIEF,
  441.          QEDIT or MicroEMACS (DOS and WINDOWS), to provide access to all
  442.          functions and  data types with just a keystroke. These features
  443.          make  a comfortable hypertext  source code  browser and locator
  444.          out  of  your editor.  A  project consisting  of  several files
  445.          appears  to  the developer  as  if it  were  a  'whole-part' of
  446.          software. The developer can walk through programs and trace the
  447.          logic  without  having to  memorize the  directories  and files
  448.          where  functions or data types are defined  and called. The SXT
  449.          windows  versions provide similar functionality  with DLL's for
  450.          database access.
  451.  
  452.          A useful  option of CST is the possibility to generate a source
  453.          file   with  which  size  and   byte  offset  calculations  for
  454.          structures/  unions and  their members  can be  performed. This
  455.          option  is  useful  especially to  support  any  kind  of error
  456.          searching  or  hardware  debugging,  for  example  with an  ICE
  457.          (Integrated Circuit Emulator), or if data structures have to be
  458.          exchanged  between different hardware  platforms with different
  459.          data alignment.
  460.  
  461.          CFT can  also be used to analyze "C"-like languages as they are
  462.          used  by  several commercial  programs.  The  macro programming
  463.          languages  of  the  BRIEF,  EPSILON  and  ME  editors are  such
  464.          languages and can be handled by CFT.
  465.  
  466.          CFT and  CST have been used since 1989 in several projects with
  467.          applications ranging from single source files over medium sized
  468.          applications  (like the  SXT programs  themselves) up  to large
  469.          software  projects with hundreds  of source  and include files,
  470.          more  than 15 MB of  source code, more than  500000 lines, 2000
  471.          functions and 800 data types.
  472.  
  473.          Many public  available C/C++ sources (e.g. GNU-C compiler, GNU-
  474.          EMACS,  MicroEMACS, NCSA TCP/IP communication software package,
  475.          SUIT -  The Simple User Interface Toolkit, NIHCL - The National
  476.  
  477.                                         8
  478.  
  479.  
  480.  
  481.          Institute  of   Health  C++  class  library,  F2C  Fortran-to-C
  482.          translator, Wolfenstein 3D game and many others) were processed
  483.          with  sometimes surprising  results during the  development and
  484.          have  been used to test and  improve the features, reliability,
  485.          correctness,  robustness and  execution speed  of CFT,  CST and
  486.          their related utilities.
  487.  
  488.          Although  the other SXT  packages are  much newer  than CFT and
  489.          CST, they all are closely related. The CXT programs are used as
  490.          the common base for all other packages.
  491.  
  492.  
  493.          3   PROGRAM DESCRIPTION
  494.  
  495.          CFT  builds a hierarchy  call tree  of every  function with the
  496.          called  functions in it's  own function  block. These functions
  497.          are  again used  as a  starting  point for  subsequent function
  498.          blocks. Starting the call tree with the "main"-function it will
  499.          display  the  complete  function flow  chart  and  the function
  500.          hierarchy  dependency of  the whole  application with  all user
  501.          defined functions  and the called library functions. Prototyped
  502.          but  never  defined  or  called  functions  are also  detected.
  503.          Recursive calls of functions are recognized and displayed, even
  504.          over   several  call  levels.  Repeated   calls  of  previously
  505.          displayed functions  in the output call tree are detected and a
  506.          message  will   be  given  with  a  reference  to  their  first
  507.          appearance.  This  prevents  the  output  of complete  subtrees
  508.          displayed  earlier. Overloaded C++ functions  and operators are
  509.          recognized and displayed with the number of overloadings.
  510.  
  511.          CST  acts similar to CFT but it  works on data types like basic
  512.          types,  structures, unions,  enumerations and C++  classes. CST
  513.          builds a  hierarchy call tree of every structure and union data
  514.          type with their internal elements and their related data types.
  515.          If  these data types  are again structures,  unions or classes,
  516.          the substructures  will again be displayed. CST recognizes data
  517.          types  defined by 'typedef' and derived  from other data types.
  518.          The  type  names  corresponding  to  the  same  basic type  are
  519.          displayed in  the output file as 'alias' names for their common
  520.          basic  data type name. Every feature of  CFT like the detection
  521.          of  recursive  declared structures  and  unions,  references to
  522.          previously  displayed data types  and others  are available and
  523.          act similar.
  524.  
  525.          Every function  (CFT) and data type (CST) can be displayed with
  526.          the  name of the  source file and  the line number  where it is
  527.          defined. The output can be customized to display the tree chart
  528.          as a  call-tree ("CALLER-CALLEE"-relation: "WHO CALLS WHOM") or
  529.          as  a caller-tree ("CALLEE-CALLER"-relation: "WHO  IS CALLED BY
  530.          WHOM").  This  feature  allows  the  user  to  determine  which
  531.          functions  are   called  from  a  specific  function  or  which
  532.          functions are callers of a specific function.
  533.  
  534.          The  function and data type extraction from  the source code is
  535.          done by scanning and parsing the source. There is absolutely no
  536.          need  for the  programmer to  mark functions  or data  types of
  537.          interest,  for  example  with  special  keywords, starting  the
  538.          definitions  at  the beginning  of a  line or  to  use comments
  539.  
  540.                                         9
  541.  
  542.  
  543.  
  544.          containing  special marks, as it is  necessary for other source
  545.          code  analyzers  and  browsers.  CFT,  CST  and  the other  SXT
  546.          programs do not need these work-arounds, any source code can be
  547.          processed without  previous work. These tools are also compiler
  548.          independent because  they can be customized to support any kind
  549.          of compiler.
  550.  
  551.          Since  the SXT programs  always make  a static  analysis of the
  552.          program source code, they are not able to detect references due
  553.          to the expansion of a macro definition during runtime. This has
  554.          to  be considered for DBASE and LISP  programs which allow such
  555.          dynamic  features. The same restrictions apply  also to the use
  556.          of  function  pointers  for  C  and  function  names as  formal
  557.          parameters  in FORTRAN which cannot be  resolved for call graph
  558.          generation.
  559.  
  560.          Several  useful  information  and  software  metrics about  the
  561.          processed  source code and the included  files can be generated
  562.          like
  563.  
  564.          - file size and comment size in bytes for every file,
  565.          - number of source code lines for every file,
  566.          - number of included files for every source file,
  567.          - total  effective number of scanned bytes  and lines for every
  568.            source  file and  its included files,  if files  are included
  569.            multiple times, this will influence the calculations,
  570.          - for every  defined function the number of lines, the code and
  571.            comment  size in  bytes, the  number of  bytes per  line, the
  572.            number  of  functions  called,  the  number  of flow  control
  573.            statements  (if,  else,  for,  while,  case,  default,  goto,
  574.            return,  exit), the  maximum brace nesting  level and  if the
  575.            function is used only inside the file,
  576.          - for  every   defined  structure/union  the  total  number  of
  577.            elements  and  the number  of elements  which  are themselves
  578.            structures/unions,
  579.          - file function or data type reference list for every file,
  580.          - total  number of  displayed,  defined, undefined  or multiple
  581.            defined functions and data types,
  582.          - location of multiple defined functions and data types,
  583.          - location of overloaded C++ functions,
  584.          - source file - include file dependencies for every source file
  585.            (MAKE-dependencies),
  586.          - source  file  -  include file  hierarchy  tree  (include file
  587.            relations),
  588.          - final statistical summary for all files,
  589.          - cross  reference of  every occurrence  for every  function or
  590.            data type,
  591.          - parent/children  relationship  for  every  function  and data
  592.            type,
  593.          - critical  function call  path/structure nesting  with deepest
  594.            non-recursive nesting level (unlimited tree depth),
  595.          - C++ class inheritance tree,
  596.          - support for C structure/union byte offset calculation,
  597.          - FORTRAN subroutine CALLs,
  598.          - FORTRAN COMMON blocks,
  599.          - generation  of description  files for  call/inheritance graph
  600.            visualization with the RATIONAL ROSE CASE tool,
  601.  
  602.  
  603.                                         10
  604.  
  605.  
  606.  
  607.          - generation  of HTML-output  for call tree  visualization with
  608.            WWW  Browsers   like  Netscape,  NCSA  Mosaic  or  MS-WinWord
  609.            Internet Assistant,
  610.          - generation  of RTF-output for  import to  word processors and
  611.            for compiling Windows Help files
  612.  
  613.          The    resulting   hierarchy   structure   chart   is   another
  614.          representation for a directed call graph. A directed call graph
  615.          consists  of nodes  (functions or  data types)  and connections
  616.          (call  relations) between these nodes. The  number of nodes and
  617.          connections  which  are necessary  to  transform  the hierarchy
  618.          structure  chart  into  a  directed  call  graph  will also  be
  619.          calculated  as  an  additional  information  about  the  system
  620.          complexity.
  621.  
  622.          A large  number of options to control the program execution and
  623.          the  output generation are available and can  be defined on the
  624.          command line,  with interactive dialog windows (applies only to
  625.          Windows  versions), by command files or by  defining them in an
  626.          environment variable used by the program.
  627.  
  628.          CFT,  CST and the  other SXT  programs can  be directly invoked
  629.          from inside editors or integrated development environments like
  630.          the  Borland  C++ IDE.  Detailed examples  for  the integration
  631.          together with necessary macro or batch files are given. The SXT
  632.          windows  versions  provide DLL's  (Dynamic  Link  Libraries) to
  633.          access  the generated  databases  and to  retrieve information.
  634.          These  DLL's  can be  used  with user  developed  programs e.g.
  635.          written  in  C,  C++,  Visual  Basic,  or  from  other  Windows
  636.          applications like MS-Word for Windows, MS-Excel and others.
  637.  
  638.  
  639.          4   LANGUAGE IMPLEMENTATION
  640.  
  641.          4.1 C-LANGUAGE IMPLEMENTATION AND C-PREPROCESSOR
  642.  
  643.          The  ISO/ANSI C language  standard ISO/IEC  9899:1990 (E) resp.
  644.          X3.159-1989-ANSI  C as described in several  books about the C-
  645.          language  (see references) was used as  a development base. The
  646.          reserved  keywords being recognized  are not  only the original
  647.          ISO/ANSI  C keywords but were also  taken from several compiler
  648.          implementations  like Microsoft, Borland  or GNU  and their own
  649.          special  language extensions.  The  books "The  C++ Programming
  650.          Language"  and  "The  Annotated  C++  Reference  Manual"  (ARM)
  651.          together  with  information  about the  work  of  the  ANSI C++
  652.          committee X3J16  resp. the ISO/IEC working group SC22 WG21 were
  653.          used  for the C++ keywords.  Another major source  was the AT&T
  654.          C++  release 2.1. Compiler specific  extensions especially from
  655.          GNU are also recognized.
  656.  
  657.          A complete list of all reserved keywords is show in appendix 2.
  658.          The  large set of keywords may lead  to some slight problems in
  659.          situations  where a  keyword is not  used as  itself but  as an
  660.          identifier  name,   for  example  a  C++  keyword  used  as  an
  661.          identifier in C.
  662.  
  663.          During  a   normal  file  scan,  precompiler  defines  are,  if
  664.          possible,  handled as if  a real precompiler  would be present,
  665.  
  666.                                         11
  667.  
  668.  
  669.  
  670.          but this  can cause some trouble with '#if', '#ifdef' and other
  671.          precompiler  controls which are  not evaluated.  Also the block
  672.          nesting  level,  which will  be  monitored by  the  source code
  673.          scanner, may  not be at level 0 at  the end of the file because
  674.          of such  precompiler controls. To avoid such things, a built-in
  675.          C-preprocessor allows  the complete preprocessing of the source
  676.          code  and  include  files  for  several  compiler  types as  an
  677.          additional option (-P).
  678.  
  679.          Preprocessing  or not is a little  bit controversial because it
  680.          can  either result in a loss of  information if macros are used
  681.          to change the program behaviour and hide function calls, it can
  682.          lead  to  errors during  file  scanning or  it  can  change the
  683.          function and data type information obtained from the code which
  684.          may  not   exactly  correspond  to  the  visible  source  code.
  685.          Preprocessing  can be an advantage  or not, so the  user has to
  686.          decide  whether he does it  or not (see options  -P, -I, -E for
  687.          more information).
  688.  
  689.          The  preprocessor  handles  the defines  for  Microsoft  C 5.1,
  690.          Microsoft  C/C++ 7.0,  Microsoft Visual  C++ 1.5 /  2.2 / 4.0 /
  691.          4.1 /  4.2, Turbo C++ 1.0,  Borland C++ 2.0 /  3.1, Borland C++
  692.          1.0  for OS/2, Watcom  C/C++ 10.0, GNU-C  2.2.2 / 2.6.3 / 2.7.2
  693.          and  Intel 80960 C compiler  iC960 3.0 and  their memory models
  694.          (if necessary)  or CPU architectures for the Intel 80960 32 bit
  695.          RISC  processor (KA, KB, SA, SB, MC,  CA). Other compiler types
  696.          can  be specified with  the -B and  the -D and  -U options. The
  697.          default  ISO/ANSI C  predefined macros  '__FILE__', '__LINE__',
  698.          '__DATE__',  '__TIME__'  are generated  for  preprocessing. The
  699.          macro  '__STDC__'  is  NOT defined  (some  compilers  test with
  700.          '#ifndef __STDC__'), so that non standard ISO/ANSI C extensions
  701.          in  the  processed code  are  allowed.  Defining '-D__STDC__=1'
  702.          forces  ISO/ANSI C  conforming output (if  used by  the scanned
  703.          source  code,  of  course!).  Additional  supported precompiler
  704.          defines     are     '__TIMESTAMP__',     '__BASE_FILE__'    and
  705.          '__INCLUDE_LEVEL__'.  A  list  of  the  predefined preprocessor
  706.          defines for the supported compiler types is shown in appendix 1
  707.          together  with  tips  for the  adaptation  of  other compilers.
  708.          Features  like  the replacing  of trigraphs,  digraphs  and the
  709.          recognition  of C++  comments '//...' are  also treated  by the
  710.          preprocessor.
  711.  
  712.          The  precompiler recognizes several errors  or possible sources
  713.          for problems like
  714.  
  715.          - the use of undefined variables in precompiler controls,
  716.          - misbalanced  '#if...'  control block(s)  including  the exact
  717.            location (file, line) where the failing block started,
  718.          - recursive called include files,
  719.          - nested include files,
  720.          - wrong number of macro arguments
  721.  
  722.          and  displays diagnostic messages with  an exact description of
  723.          the  error or  warning reason  and its  location in  the source
  724.          file.
  725.  
  726.  
  727.  
  728.  
  729.                                         12
  730.  
  731.  
  732.  
  733.          4.2 C++ LANGUAGE IMPLEMENTATION
  734.  
  735.          For  the description of the related  C++ language standards and
  736.          other   literature  see  the  chapter   about  the  C  language
  737.          implementation.
  738.  
  739.          Although  CFT and CST  were initially not  developed to process
  740.          C++  code it is possible  to do so.  However, some restrictions
  741.          and  limitations should be  considered. The  recognition of C++
  742.          classes  by CST is limited  because the handling  of classes is
  743.          too  complex.  Classes  are only  referenced  by  name  but the
  744.          internal  structure will not be scanned  and displayed. The C++
  745.          class  inheritance relationships are recognized  and shown in a
  746.          class  hierarchy graph listing  (option -b).  Structures in C++
  747.          with  functions  as  structure members  will  not  be processed
  748.          correctly,  function bodies  inside a structure  definition may
  749.          cause  errors.  Templates are  not  supported and  will  not be
  750.          recognized.
  751.  
  752.          Calling  member functions will not  be recognized correctly due
  753.          to missing class name and name scope resolving, this leads also
  754.          to  an incomplete CFT  call tree and  a lot  of warnings during
  755.          analysis. The  use of overloaded functions with equal names but
  756.          different  parameters  in C++  programs may  lead  to incorrect
  757.          calling   relationships.   A   variable   initialization   with
  758.          parameters will be misinterpreted as a function call. A correct
  759.          handling  of these and  other C++ features  requires a complete
  760.          C++  source code analyzer to keep track  of the class functions
  761.          belong to and the different calling parameters.
  762.  
  763.          If precise information about C++ code is needed, utilities like
  764.          'class  hierarchy  browsers'  or  'class  viewers',  which  are
  765.          usually  part  of  C++ compiler  environments,  should  be used
  766.          instead.
  767.  
  768.  
  769.          4.3 DBASE SOURCE CODE
  770.  
  771.          DFT can  process source code which is based on the DBASE III/IV
  772.          programming language.  This means that also source code written
  773.          in  DBASE  derivatives like  CLIPPER (Summer  '87)  or probably
  774.          FOXBASE  can be analyzed. The source code  analyzer tries to be
  775.          as  correct as possible to  build a reliable  hierarchy tree. A
  776.          function/  procedure declaration is recognized  by the FUNCTION
  777.          resp.   PROCEDURE   keyword.  A   function/procedure   call  is
  778.          recognized by the following statements:
  779.  
  780.               function()
  781.               CALL function
  782.               CALL function WITH parameters
  783.               DO function
  784.               DO function WITH parameters
  785.  
  786.          If  a  file contains  no function/  procedure  declaration, the
  787.          filename itself  is taken as procedure name. The recognition of
  788.          built-in functions/  procedures can be ignored (see option -E).
  789.          All  tokens  are assumed  case-insensitive  and  are internally
  790.          converted    to   upper-case    characters.   System   built-in
  791.  
  792.                                         13
  793.  
  794.  
  795.  
  796.          functions/macros  can be specified by  option -E. Include files
  797.          (e.g.  with CLIPPER)  are not  processed.  The Clipper  5 C/C++
  798.          style  comments   /*...*/  resp.  //  are  (hopefully  correct)
  799.          recognized.
  800.  
  801.  
  802.          4.4 FORTRAN SOURCE CODE
  803.  
  804.          FFT  can  process  source which  is  based  on  the  FORTRAN 77
  805.          standard.  Each FORTRAN  line is  divided  into fields  for the
  806.          required   information,   each  column   represents   a  single
  807.          character.
  808.  
  809.          COLUMN    FIELD
  810.          1         comment indicator (C,c,*,!)
  811.          1-5       label
  812.          6         indicator for line continuation
  813.          7-72      statement field (standard is 72, extended to 132)
  814.  
  815.          FFT can process lines up to 132 columns, however, if characters
  816.          are found beyond column 72 a warning will be given (this can be
  817.          disabled  with -NOWARN72). Note that the  default TAB-size of 8
  818.          characters  may lead sometimes to  such unwanted messages which
  819.          might  no occur with TAB-size 6.  Continuation lines are merged
  820.          before  they are analyzed. The number  of continuation lines is
  821.          19  by default  and can  vary between  0  and 99  (option -qn).
  822.          Inline  comments in  the statement field  start with  '!', text
  823.          until end  of line is ignored. The standard intrinsic functions
  824.          and  additional VAX-FORTRAN intrinsic functions are recognized.
  825.          Statement functions  (comparable to C function-like macros) are
  826.          not recognized and may lead to 'undefined functions'. Hollerith
  827.          constants  are  not  recognized  and  handled.  All tokens  are
  828.          assumed   case-insensitive  and  are  converted  to  upper-case
  829.          characters.  Blanks are not significant  and are removed except
  830.          inside  character   strings.  If  option  -I  is  set,  INCLUDE
  831.          statements  are   recognized  and  processed.  To  handle  this
  832.          implementation  dependent feature,  several different  types of
  833.          include statements are accepted:
  834.  
  835.          C FORTRAN-LIKE SYNTAX, INCLUDE STATEMENT STARTS IN COLUMN 7
  836.               include-statement include-filename
  837.  
  838.          C C-LIKE SYNTAX, INCLUDE STATEMENT STARTS IN COLUMN 1
  839.               include-statement include-filename
  840.  
  841.          where  include-statement is one of  INCLUDE, #INCLUDE, $INCLUDE
  842.          or   %INCLUDE  and  include-filename  is   one  of  'filename',
  843.          "filename",   <filename>   or  filename   (without  surrounding
  844.          characters).  See  option  -I  and  the  chapter about  PROGRAM
  845.          LIMITATIONS for additional information about file inclusion.
  846.  
  847.          The  resulting function call graph may be  incorrect due to the
  848.          ENTRY  capability of FORTRAN  which allows direct  jumps into a
  849.          function  or subroutine body from the  outside. This may result
  850.          in  incorrect  relationships for  the ENTRY  statement  and the
  851.          surrounding function/subroutine. The indirect call of functions
  852.          which  are   given  as  formal  parameters  to  subroutines  or
  853.          functions  (comparable to pointers  to functions in  C) are not
  854.  
  855.                                         14
  856.  
  857.  
  858.  
  859.          correctly  referenced. Implicit typing for function definitions
  860.          without  return type will not be  recognized, the function will
  861.          be displayed without a return type.
  862.  
  863.  
  864.          4.5 LISP SOURCE CODE
  865.  
  866.          LFT can process LISP and SCHEME source code. The development of
  867.          LFT  was mainly based  on the GNU-EMACS  LISP dialect  as it is
  868.          used  in   the  GNU-EMACS  macro  extension  language  and  its
  869.          functionality  was tested mainly  with these  macro files. LISP
  870.          functions/macros  are  recognized  by  the  DEFUN and  DEFMACRO
  871.          keywords.  SCHEME   functions  are  recognized  by  the  DEFINE
  872.          keyword,  SCHEME  processing  is  enabled  by option  -XSCHEME.
  873.          Unnamed  functions  declared  with the  LAMBDA  keyword  can be
  874.          recognized  optionally  (option -XLAMBDA).  Tokens  are assumed
  875.          case-sensitive.  Comments are recognized for  ';' until end-of-
  876.          line and between '#|' and '|#' as multi line comment blocks.
  877.  
  878.          The source  code analysis is performed in two passes: The first
  879.          pass  detects function/macro  declarations and the  second pass
  880.          analyzes the relationships. Function calls via (funcall <fcn>),
  881.          (function  <fcn>),  (apply  <fcn>),  (mapc  <fcn>) and  similar
  882.          constructs may not be correctly evaluated if fcn is a function-
  883.          symbol  (e.g. given as  a function  parameter) and  not a valid
  884.          function   name.  System   built-in  functions/macros   can  be
  885.          specified by option -E.
  886.  
  887.          LFT  was designed to work  with different types  of LISP source
  888.          code (as  there are XLISP, CLOS, GNU-EMACS LISP, ...), although
  889.          the large number of dialects may lead sometimes to problems.
  890.  
  891.  
  892.          4.6 ASSEMBLER SOURCE CODE
  893.  
  894.          As  an additional  feature, CFT and  FFT can  process assembler
  895.          source code for the Intel 80x86 processors (MASM 5.1, TASM) and
  896.          for  the Intel 80960 RISC processors (or  any other "AT&T UNIX-
  897.          like  assembler" like GNU)  to get  information about assembler
  898.          procedures and functions being called from the assembler source
  899.          files.  This feature is useful  for mixed language programming.
  900.          The  assembler  source code  scanner also  detects  and handles
  901.          calls  of include  files. The  processing of  assembler macros,
  902.          however, is  not supported, the preprocessing option (-P) works
  903.          only on C source code. Assembler source files are recognized by
  904.          their file extensions '.ASM' and '.S', there is no other way to
  905.          force a file being processed as an assembler file.
  906.  
  907.          The  following naming convention is  used: For '.ASM' assembler
  908.          files (MASM, TASM) all identifiers are treated case-insensitive
  909.          and  will be transformed to lower (CFT)  resp. upper (FFT) case
  910.          characters, but identifiers in '.S' (GNU, I960) assembler files
  911.          are  treated  case-sensitive.  This  means,  that an  assembler
  912.          function  'func1' defined in an '.ASM' file  can be called from
  913.          the source  by 'func1', 'FUNC1', 'Func1' or any other lower and
  914.          upper  case character combination. If 'func1'  is defined in an
  915.          '.S'  file,  the name  must  match exactly.  The  first leading
  916.          underscore  of a  function name  will be  removed to  get exact
  917.  
  918.                                         15
  919.  
  920.  
  921.  
  922.          naming matches. Type modifiers in C source code like 'cdecl' or
  923.          'pascal'  will not  be  considered. Remember  these conventions
  924.          when processing C, FORTRAN and assembler files.
  925.  
  926.          Assembler  code statements (inline  code) inside  C source code
  927.          will  not be processed and  will be skipped, because  it is too
  928.          difficult to  handle the several kinds of syntax being used for
  929.          this  like  'asm  ...',  'asm  "..."'  or  'asm(...)'  and  the
  930.          different  keywords  ('asm', '_asm',  '__asm',  '__asm__', ...)
  931.          used by various compiler implementations.
  932.  
  933.  
  934.          5   DATABASE GENERATION
  935.  
  936.          One  of the most important features  is the database generation
  937.          (option  -G). It is performed after writing  the output file to
  938.          save  all  information about  the  processed files  in  a dBASE
  939.          compatible  database for later use.  The database files contain
  940.          all necessary information like function or data type names, the
  941.          location   where   they   are   defined,   their  caller/callee
  942.          relationship,  all  scanned files  with  statistic information,
  943.          include files  and so on. I have tried to store the information
  944.          in  the most compact  and effective database  structure to save
  945.          disk space.  Note that if the contents of the database files is
  946.          manipulated by external tools like dBASE or something else, the
  947.          internal consistency  will be corrupted and wrong or unexpected
  948.          results will happen!
  949.  
  950.          The database  can be used to recall information, for example to
  951.          find  out, if and  in which file  and on which  line a specific
  952.          function  or  data type  is  defined. A  database  can  be read
  953.          (option  -g) to add new files and/or  to produce another output
  954.          file with  new options, for example with a reverse call tree or
  955.          only  with a  special selected  item  being displayed.  Such an
  956.          incremental  database   generation  is  also  useful  if  large
  957.          projects can  be divided into a set of common files and project
  958.          specific files.  A good example for this is the GNU C compiler,
  959.          which consists of language independent files and three language
  960.          dependent file sets for C, C++ and Objective-C. To analyze this
  961.          software  the language  independent part can  be stored  into a
  962.          database which is later reused for the language dependent parts
  963.          to  build the complete set  of information. Note  that there is
  964.          currently  no possibility  to update  the analysis  results for
  965.          files  which  are  already in  the  database  and  have changed
  966.          afterwards,  the  user  is  only  informed  about  such  files.
  967.          Currently  it is only possible  to add files but  not to update
  968.          analysis results.
  969.  
  970.          The ability  to retrieve information about the sources from the
  971.          database is  useful in many cases. Recalling information from a
  972.          database  is much faster than processing  all the sources again
  973.          to  find a  specific item  of  interest. The  documentation and
  974.          maintenance  of large software projects  is much more effective
  975.          and  easier  to do  if the  developer  has a  tool  to navigate
  976.          through the source code and that helps him in his comprehension
  977.          of  the program and its  internal structure. It  is also useful
  978.          for  reverse engineering of source  code to get  an overview of
  979.          the internal program structure. Together with user programmable
  980.  
  981.                                         16
  982.  
  983.  
  984.  
  985.          editors  it is possible to  offer a source code  browser with a
  986.          hypertext   like  feeling  by  integrating  database  recalling
  987.          functions into the editors.
  988.  
  989.          Additional   utility  programs  to  retrieve  information  from
  990.          databases, called  CFTN and CSTN (for CFT, CST), are available.
  991.          Supporting  macros for their integration  into the BRIEF, QEDIT
  992.          or  MicroEMACS editor are described in  another section of this
  993.          manual.  The SXT windows versions provide  also an interface to
  994.          the databases via DLL's which are part of the Windows version.
  995.  
  996.  
  997.          6   PROGRAM LIMITATIONS
  998.  
  999.          First  of all, CFT and CST (and  the other SXT programs) cannot
  1000.          replace  a compiler or a  syntax checker like  'LINT' to detect
  1001.          errors  in  the  source code.  This  means  that  it  should be
  1002.          possible to compile the source code without fatal errors before
  1003.          it is  possible to analyze it, otherwise the processing results
  1004.          may be incorrect (and may be the system crashes ...).
  1005.  
  1006.          However,  there are some  situations where  CFT and  CST can be
  1007.          useful  to detect bugs  and inconsistencies in  the source code
  1008.          like
  1009.  
  1010.          - multiple definitions of functions or data types,
  1011.          - different function return types,
  1012.          - implicit declared functions with no prototype,
  1013.          - function definitions used as prototype,
  1014.          - recursive,  nested,  hidden  and  frequent  calls of  include
  1015.            files,
  1016.          - unterminated strings or character constants,
  1017.          - nested comments,
  1018.          - unterminated comments at end of file,
  1019.          - misbalanced braces,
  1020.          - unexpected end-of-file characters inside files,
  1021.          - illegal characters in the source code,
  1022.          - wrong number of macro arguments,
  1023.          - missing macro arguments,
  1024.          - misbalanced '#if...' control blocks.
  1025.  
  1026.          These  code  checks  are done  on  multiple  files  in multiple
  1027.          directories so that inconsistencies between different files can
  1028.          be found and displayed. This is a capability which conventional
  1029.          compilers  working  only on  a  single file  at  a  time cannot
  1030.          provide  and will  miss therefore (maybe  the linker  will find
  1031.          some of these inconsistencies).
  1032.  
  1033.          Statistical  information  about  the  source  code  may not  be
  1034.          correct  if  preprocessing is  enabled  (-P). The  size  of the
  1035.          'pure' source code may not be correct due to macro expansion or
  1036.          removing of unnecessary blanks. However, the total file size is
  1037.          always correct because it will be taken from the source file.
  1038.  
  1039.          Some  limitations for the real mode versions  are caused by the
  1040.          amount  of available  memory. The use  of memory  managers like
  1041.          EMM386,  QEMM or 386MAX can help to  get more free conventional
  1042.          memory.  If  memory problems  ("out of  memory"  message) occur
  1043.  
  1044.                                         17
  1045.  
  1046.  
  1047.  
  1048.          during  processing, the 32  bit protected mode  versions of CFT
  1049.          and  CST, called CFT386 and CST386, should  be used, which have
  1050.          no  memory limitations and are  much faster than  the real mode
  1051.          versions. There  are also SXT versions for Windows 3.1, Win32s,
  1052.          Windows   NT,  Windows  95  and  OS/2   which  have  no  memory
  1053.          limitations.
  1054.  
  1055.          The  number and the  sizes of files  to be  processed is nearly
  1056.          unlimited  with 2^14 files and 2^31  bytes maximum file length.
  1057.          Each file can have 2^16 lines. The number of functions and data
  1058.          types being  handled is limited to 2^14. These values are given
  1059.          for the real mode versions, the protected mode versions usually
  1060.          exceed  them. These limitations  should be enough  even for the
  1061.          biggest project that could be mentioned.
  1062.  
  1063.          The ISO/ANSI  C minimum requirement for include file nesting is
  1064.          8  levels and  will be fulfilled  by CFT  and CST.  The maximum
  1065.          include  file nesting level is  limited by the  number of files
  1066.          (streams)  which  can  be  opened  simultaneously.  This  is  a
  1067.          compiler specific limit usually coming from the library startup
  1068.          code.  The number  of open  files (streams)  is defined  by the
  1069.          macro   FOPEN_MAX  in   the  include  file   'stdio.h'.  During
  1070.          preprocessing  the number of nested files  is usually less than
  1071.          FOPEN_MAX because  several streams are used for the default I/O
  1072.          (stdin, stdout,  stderr, stdaux, stdprn). Also the preprocessor
  1073.          needs  additional  streams  besides those  for  the  source and
  1074.          include  files: One stream  for the temporary  output file, one
  1075.          for  a log-file (if option -L  is set) and one  for a file list
  1076.          file  (if this  is declared on  the command  line with  @). The
  1077.          maximum number of files being opened simultaneously differs for
  1078.          the various  SXT program versions due to the built-in limits of
  1079.          the different  compilers used to produce them. All SXT programs
  1080.          which  process include files (CFT, CST, FFT)  should be able to
  1081.          handle at least 10 include nesting levels. The message for such
  1082.          an include file open error is 'too many open files'.
  1083.  
  1084.          The  integrated  C-preprocessor  limits  the  size of  expanded
  1085.          macros to 6 Kbytes. The number of macros simultaneously defined
  1086.          is  unlimited   (ISO/ANSI:  1024)  and  only  affected  by  the
  1087.          available memory.  The number of macro parameters is limited to
  1088.          31 (ISO/ANSI: 31) and there are up to 31 significant characters
  1089.          (ISO/ANSI:  31) recognized. The conditional compilation nesting
  1090.          levels  of '#if  ... #endif'  control blocks  is limited  to 32
  1091.          (ISO/ANSI: 8).
  1092.  
  1093.          The line length is unlimited (ISO/ANSI: logical (?) line length
  1094.          is  509  characters).  The number  of  characters  in  a string
  1095.          (including '\0') is 2048 (ISO/ANSI: 509). The number of members
  1096.          in one structure/union is unlimited (ISO/ANSI: 127), the number
  1097.          of structure/union nesting levels is unlimited (ISO/ANSI: 15).
  1098.  
  1099.          The recognition of C/C++ identifiers like function and variable
  1100.          names  follows the  standard rules:  an identifier  consists of
  1101.          upper  and lower  case letters (A-Z,  a-z), underscore  (_) and
  1102.          digits  (0-9),   additionally  the  dollar  sign  ($)  will  be
  1103.          accepted.  National character set extensions  as they are usual
  1104.          for  languages in European  countries like  Germany, Denmark or
  1105.          Sweden can be defined with option -J.
  1106.  
  1107.                                         18
  1108.  
  1109.  
  1110.  
  1111.  
  1112.          C++ comments '//...' are usually only recognized if option -C++
  1113.          is  set. However, to accept the  non-standard extension of some
  1114.          compilers  which allow  such comments  also  in C  source code,
  1115.          option  -//  can be  used  therefore. Nested  C  style comments
  1116.          '/*...*/' are not allowed and will always produce warnings.
  1117.  
  1118.          CFT  and CST may  produce warnings  with wrong  line numbers if
  1119.          preprocessing is  enabled (option -P) and if the warning occurs
  1120.          inside   a   comment.   The   reason   is   that  line   number
  1121.          synchronization  with   '#line  ...'  is  only  guaranteed  for
  1122.          executable source but not for comments. In such a situation the
  1123.          source  code should be processed without -P  to get the correct
  1124.          line  number (such warnings  are usually  related to unexpected
  1125.          characters).
  1126.  
  1127.          The  use  of explicit  preprocessor #line  directives  in C/C++
  1128.          source   leads   to  different   results   for   the  'logical'
  1129.          (synchronized  with #line) and physical  file line numbers. CFT
  1130.          and  CST use  the 'logical' line  numbers and  therefore moving
  1131.          inside a file with an editor to a specific line may fail.
  1132.  
  1133.          The  calculation depth  of the critical  function call  path or
  1134.          structure  nesting level  is unlimited.  The calculation  is an
  1135.          extremely recursive  function and was successfully tested up to
  1136.          more than 100 nesting levels. It is not known for which nesting
  1137.          level a stack overflow will happen.
  1138.  
  1139.          CFT  cannot recognize and  reference a  function if  it is used
  1140.          with  its  pure name  without  parentheses. This  happens  if a
  1141.          function  name is  assigned to a  function pointer  variable or
  1142.          used  as  a  function  pointer  argument  in  a function  call.
  1143.          Indirect  calls to a function via a  function pointer cannot be
  1144.          resolved. A  similar case with FFT is the use of function names
  1145.          as formal parameters for calls to subroutines or functions.
  1146.  
  1147.          CFT  will be confused  in some cases  by extensive type-casting
  1148.          operations  like  'void  __based(void)  *  __cdecl  ... ()'  or
  1149.          '__declspec(...)'  and  will  display  unexpected  messages.  A
  1150.          function   prototype  declaration   inside  a   function  block
  1151.          ('function  given scope') will  not be  recognized by  CFT as a
  1152.          prototype  declaration,  instead it  will be  interpreted  as a
  1153.          function  call. In assembler  source code,  some definitions of
  1154.          local  variables  seem  to look  like  a  function  or  a label
  1155.          definition  and are treated by CFT like  that although this may
  1156.          be  wrong in  some cases.  It is  also  not always  possible to
  1157.          detect  a  call  of  a  local  label  correctly. CFT  sometimes
  1158.          displays  warning messages about 'return  type mismatch' though
  1159.          this may  be correct in that special case because the different
  1160.          types  are  earlier  defined by  a  'typedef'  declaration. The
  1161.          reason  is simply that  CFT doesn't  recognize these 'typedef's
  1162.          (but CST does), it looks only for function names.
  1163.  
  1164.          An  often requested feature for  CST is the  integration of the
  1165.          calculation   of   structure/union  sizes   with   byte  offset
  1166.          information  for every structure/union member.  This feature is
  1167.          not  implemented in CST. The reason is  that this would require
  1168.          CST   to  treat  the  various   compiler  implementations  with
  1169.  
  1170.                                         19
  1171.  
  1172.  
  1173.  
  1174.          different  basic type sizes  (sizeof(int), sizeof(long double))
  1175.          for different processor types (16 bit, 32 bit, 64 bit, ...) and
  1176.          data   type  alignment   requirements  (by  default   and  also
  1177.          controlled with  #pragma's like 'align' or 'pack'). It would be
  1178.          possible   to   do  this   for  just   one   selected  compiler
  1179.          implementation or  processor type but not for several different
  1180.          compilers. Especially compilers for advanced architectures like
  1181.          RISC   processors  have   very  complicated   alignments  rules
  1182.          depending  on  the  data  types,  alignment  pragmas,  compiler
  1183.          switches,  type sizes,  available register number  and register
  1184.          sizes  and  resulting structure/union/class  sizes  to generate
  1185.          highly  optimized code. This includes  usually the insertion of
  1186.          'fill'  bytes inside  a structure/union and  sometimes 'padding
  1187.          bytes'  at the end of a structure/union  to force aligned sizes
  1188.          on  specific byte  boundaries (For  examples see  the reference
  1189.          manual  of  the  Intel 80960  C-Compiler  iC960,  release 3.0).
  1190.          Because   of  these   reasons,   an  integrated   'byte  offset
  1191.          calculation' is  not implemented in CST. Instead, a source file
  1192.          for selected  data types can be generated with option -O, which
  1193.          performs these  calculations, if you compile the generated file
  1194.          with   your  C  compiler.  For   further  information  see  the
  1195.          description for option -O.
  1196.  
  1197.          Option  -z  in combination  with option  -I  produces redundant
  1198.          results with CFT, CST and FFT if files with executable code (or
  1199.          something that can be interpreted as that, e.g. function calls,
  1200.          data  types or  COMMON blocks) are  included directly  inside a
  1201.          function  or data type block (especially  in FORTRAN this seems
  1202.          to  be common practice  to include COMMON  blocks into function
  1203.          and subroutine  bodies). For CFT and CST (but not for FFT) also
  1204.          the  call  tree  references will  be  incomplete  and therefore
  1205.          incorrect.  With option  -P for  CFT  and CST  everything works
  1206.          fine, because the preprocessor works more precise as the simple
  1207.          file inclusion mechanism option -I uses.
  1208.  
  1209.  
  1210.          SUMMARY
  1211.  
  1212.          The above  described limitations can lead in some situations to
  1213.          misinterpretations or loss of information of the scanned source
  1214.          code. The  only way to avoid these lacks would be the inclusion
  1215.          of  parts of a 'real compiler' to  handle the complete language
  1216.          syntax  in  any  possible  situation.  But  this  was  not  the
  1217.          intention  when the development  of these  programs as 'little'
  1218.          and  easy to use  general purpose  programming supporting tools
  1219.          began. Although I hope that the SXT programs will in most cases
  1220.          be powerful and useful development and documentation tools!
  1221.  
  1222.  
  1223.          7   SXT OPTIONS
  1224.  
  1225.          This  section gives a  complete overview about  all SXT options
  1226.          and their syntax. It gives also remarks for their use and shows
  1227.          several  examples with  detailed descriptions. The  options are
  1228.          case-sensitive! There  are no differences between the real mode
  1229.          and  the other  versions of  the SXT  programs. In  the Windows
  1230.          versions,  all options can be set both  on the command line and
  1231.          by menu selections and dialog windows. For every option the SXT
  1232.  
  1233.                                         20
  1234.  
  1235.  
  1236.  
  1237.          programs  which  support  it are  listed  in  parentheses. This
  1238.          section of the documentation should be read very careful by all
  1239.          users  to  get an  overview about  all the  features  which are
  1240.          provided.
  1241.  
  1242.          THE OPTIONS  ARE LISTED IN LEXICOGRAPHICAL ORDER. NONE OF THESE
  1243.          OPTIONS IS SET BY DEFAULT.
  1244.  
  1245.          SYNTAX:   CFT  [options [$cmdfile]] <[+]file> <@filelist>
  1246.                    CST  [options [$cmdfile]] <[+]file> <@filelist>
  1247.                    DFT  [options [$cmdfile]] <[+]file> <@filelist>
  1248.                    FFT  [options [$cmdfile]] <[+]file> <@filelist>
  1249.                    LFT  [options [$cmdfile]] <[+]file> <@filelist>
  1250.  
  1251.  
  1252.          OPTIONS: (valid for SXT program)
  1253.  
  1254.  
  1255.          -Bsizes        (CFT, CST)
  1256.          Redefine  the  basic type  sizes  and pointer  type  sizes (all
  1257.          values must  be declared in bytes) for conditional preprocessor
  1258.          controls  with the 'sizeof()' keyword  like '#if sizeof(int) ==
  1259.          4'. This option is only valid with the -P option.
  1260.  
  1261.          The required format for this option is
  1262.  
  1263.               -Bv,c,s,i,l,f,d,ld*data,code
  1264.               (delimiter between data and pointer sizes is '*')
  1265.  
  1266.          with the following types and their respective default data size
  1267.          values in bytes (the pointer type sizes are model dependent):
  1268.  
  1269.          v :    void (sizeof(void) is usually 0, but for GNU-C it is 1)
  1270.          c :    char (1 byte)
  1271.          s :    short (by definition 2 bytes, hardware independent)
  1272.          i :    integer (hardware dependent, 2 or 4 bytes)
  1273.          l :    long (4 bytes)
  1274.          f :    float (4 bytes, IEEE format)
  1275.          d :    double (8 bytes, IEEE format)
  1276.          ld :   long  double  (10  bytes,  IEEE  format, some  compilers
  1277.                 assume long double == double (= 8 bytes), some CPU's and
  1278.                 their compilers have special alignment requirements like
  1279.                 the  Intel 80960, where sizeof(long  double) is 16 bytes
  1280.                 due  to  register  and  memory  access requirements  and
  1281.                 structure alignment)
  1282.          data : data pointer (type  pointers, 2 or 4 bytes, memory model
  1283.                 dependent)
  1284.          code : code  pointer (function pointers,  2 or  4 bytes, memory
  1285.                 model dependent)
  1286.  
  1287.          The sizes  of signed and unsigned types of the same basic types
  1288.          are  considered  equal,  this  means  that,  for  example,  the
  1289.          following expression is true:
  1290.  
  1291.               sizeof(unsigned int) == sizeof(signed int) == sizeof(int)
  1292.  
  1293.  
  1294.  
  1295.  
  1296.                                         21
  1297.  
  1298.  
  1299.  
  1300.          The  sizes of type  pointers to  data and  function pointers to
  1301.          code  are also considered equal, this  means that, for example,
  1302.          the following expressions are true:
  1303.  
  1304.               sizeof(int *) == sizeof(float *)
  1305.               sizeof(int (*)()) == sizeof(float (*)())
  1306.  
  1307.          A  64  bit (8  bytes)  integer  type like  'long  long  int' or
  1308.          'bigint'  (or   something  else)  is  currently  not  supported
  1309.          although some (co-) processors and their assemblers are able to
  1310.          handle it (see Intel 80960 assembler manual for examples). Also
  1311.          the  DEC Alpha  processor with its  64 bit  architecture should
  1312.          support this.
  1313.  
  1314.          If the -B option is not set, the default values for the various
  1315.          memory models  and compiler types (as they are known to me) are
  1316.          used,   the  assumed  target   hardware  has   an  Intel  80x86
  1317.          microprocessor.    Note   that    during   preprocessing   type
  1318.          modificators like "near" or "far" are not recognized.
  1319.  
  1320.          If  the -B and the  -T options are  not set, the  sizes of data
  1321.          pointers and code pointers are always considered equal:
  1322.  
  1323.               sizeof(int *) == sizeof(int (*)()) (= 4, large model)
  1324.  
  1325.          For   example,  -B0,1,2,2,4,4,8,10*4,4  would  be  the  correct
  1326.          declaration  for MS-C  7.0, large/huge  memory model,  with the
  1327.          values for data types  (void = 0, char = 1, short = 2, int = 2,
  1328.          long = 4, float = 4, double = 8 and long double = 10 bytes) and
  1329.          pointers  to data  types and  function  pointers (all  values 4
  1330.          bytes).   These  values  are  set   automatically  by  defining
  1331.          -TMSC70,L  (or  -TMSC70,H) as  compiler type  and  memory model
  1332.          description for preprocessing.
  1333.  
  1334.  
  1335.          -BATCH[inifile]     (SXT WINDOWS VERSIONS ONLY)
  1336.          This  command  line option  can only  be used  with  the SXTWIN
  1337.          programs. It allows to start a SXTWIN program in batch mode via
  1338.          the 'File'  'Run' menu or any other program. The SXTWIN program
  1339.          executes the  commands (from the command line and INI-file) and
  1340.          is  closed automatically  after  having finished.  The optional
  1341.          parameter     'inifile'    specifies    the    complete    name
  1342.          (drive:/dir/filename)  of the INI-file that  should be used for
  1343.          analysis.
  1344.  
  1345.  
  1346.          -C++           (CFT, CST)
  1347.          Enable C++ source code processing. This includes the definition
  1348.          of   the  macro  name  '__cplusplus'   for  preprocessing,  the
  1349.          recognition  of C++ keywords  and the handling  of C++ comments
  1350.          '//...'.  Option -C++  is strictly  recommended to  process C++
  1351.          code.
  1352.  
  1353.  
  1354.          -C[s]               (CFT, CST, DFT, FFT, LFT)
  1355.          List the  function/data type contents for every processed file,
  1356.          's'  sorts by  line  numbers (DEFAULT  ORDER: lexicographical).
  1357.          There are additional information possible with the option -s. A
  1358.  
  1359.                                         22
  1360.  
  1361.  
  1362.  
  1363.          remark  is given if none of the  functions defined in a file is
  1364.          called  from functions defined in  other files (internal versus
  1365.          external  linkage).  Functions  for  which  no external  caller
  1366.          outside  the  file is  found  will be  marked  [INTERNAL], such
  1367.          functions are candidates for defining them as 'static' (Calling
  1368.          a  function  by a  function  pointer won't  be  noticed!). This
  1369.          information  is useful to  find out  whether the  contents of a
  1370.          file  is unnecessary for the project so  that the file must not
  1371.          be  linked. This option  gives useful  information about source
  1372.          code metrics for every defined function. Most of the values are
  1373.          given in the format "average [minimum ... maximum]". Almost the
  1374.          same information  is provided for data types with CST. For CFT,
  1375.          the  values may not be correct if  '#if line...' constructs are
  1376.          used  with not strictly ascending  line numbers as  they may be
  1377.          generated by tools like LEX or YACC!
  1378.  
  1379.  
  1380.          -CALL          (FFT)
  1381.          Recognize and  display only subroutine 'CALL ...' statements in
  1382.          a function or subroutine body. In some cases this option can be
  1383.          useful  if the  source code  scanner  gets confused  by indexed
  1384.          array accesses which might be misinterpreted as function calls.
  1385.          With this option only the 'CALL ...' statements are detected.
  1386.  
  1387.  
  1388.          -CLIPPER       (DFT)
  1389.          Handle  CLIPPER specific extensions: comments  '//' and '/* */'
  1390.          and extended character set ':{}'.
  1391.  
  1392.  
  1393.          -COMMON        (FFT)
  1394.          Recognize  and display  COMMON block names.  The block  name is
  1395.          surrounded  by '/' like /name/,  a blank COMMON  block is named
  1396.          //.  In the output  file, COMMON  block names  are handled like
  1397.          function  names, e.g. the call statistics  says '# calls'. Note
  1398.          that the  BRIEF and MicroEMACS macros cannot handle block names
  1399.          correctly since they do not accept the '/' character.
  1400.  
  1401.  
  1402.          -CTAGS[x]      (CFT)
  1403.          This option generates a CTAGS file with information for VI-like
  1404.          tagging of  defined identifiers. The CTAGS file is named "TAGS"
  1405.          by default unless the optional extension 'x' is used to specify
  1406.          another filename. Each entry in the TAGS file has the format
  1407.  
  1408.               identifier<tab>file<tab>vi-search-pattern
  1409.  
  1410.          where 'vi-search-pattern'  is a regular expression matching the
  1411.          line  where  'identifier'  is  defined.  This  is  the  default
  1412.          implementation  for   CTAGS.  The  generated  TAGS  files  were
  1413.          successful  tested with the MSDOS versions  of VI (from Mortice
  1414.          Kern  Systems Inc.) and  the public domain  VI-clone ELVIS, but
  1415.          should  also work with  other VI versions.  Since VI originates
  1416.          from  UNIX, the TAGS file contains only  LF, not CR+LF, as line
  1417.          ending. I have done it this way to avoid possible problems with
  1418.          close-to-UNIX VI  ports, but this may also lead to new problems
  1419.          if  CR+LF is really needed.  To change from DOS  to UNIX styles
  1420.  
  1421.  
  1422.                                         23
  1423.  
  1424.  
  1425.  
  1426.          and  vice versa, tools like  DOS2UNIX or UNIX2DOS  can be used.
  1427.          See also option -TAGS for additional information.
  1428.  
  1429.          This    option   cannot   work   together    with   option   -P
  1430.          (preprocessing),  this applies  also to results  generated from
  1431.          databases previously created with option -P. The reason is that
  1432.          the  preprocessed source does  usually not  correspond with the
  1433.          original  source,  it  contains  additional  #line  directives,
  1434.          comments and  obsolete blanks are removed, file offsets are not
  1435.          valid.  Therefore the option -CTAGS  can only be  used with the
  1436.          original source code.
  1437.  
  1438.  
  1439.          -D[..]              (CFT, CST, DFT, FFT, LFT)
  1440.          Specifies macro  name(s) (-Dname or -Dname1=name2) or file with
  1441.          macro names  (-D@namelist) of functions/data types which should
  1442.          be  predefined and linked  together, also  used as preprocessor
  1443.          define  if  the  integrated preprocessor  is  called  (-P). The
  1444.          defined  names  are  case sensitive  and  trigraph  and digraph
  1445.          translation  is performed  on them.  For preprocessing,  the -D
  1446.          option has lower precedence than the -U option. That is, if the
  1447.          same name is used in both a -U option and a -D option, the name
  1448.          will be undefined regardless of the order of the options.
  1449.  
  1450.          The  definition of a string as replacement  for a macro name is
  1451.          different  on the  command line and  inside a  macro definition
  1452.          file  or command file (marked  with '$'). On  the command line,
  1453.          the  double quotation  marks must be  'escaped' and  the string
  1454.          must be quoted like '-DXYZ="\"123\""' (similar to C strings) to
  1455.          work correctly, the reason is the DOS wildcard expansion of the
  1456.          command  line. Inside a  macro definition or  command file, the
  1457.          double quotation marks need not be 'escaped', so the definition
  1458.          can  be written like '-DXYZ="123"'. This  option cannot be used
  1459.          in  environment defines if the  equal sign '='  is used because
  1460.          this  produces a syntax  error for DOS  when trying  to store a
  1461.          'SET=...'  command with a second  equal sign in one  line. If a
  1462.          define  item consists of two  words see the notes  at option -S
  1463.          for  a description.  Keep these  differences and  exceptions in
  1464.          mind to avoid unexpected results using the -D option.
  1465.  
  1466.  
  1467.          -Ename         (CFT, CST, FFT)
  1468.          Almost the  same as -I, but the path for the include files will
  1469.          be taken from the environment variable 'name'. Typing -EINCLUDE
  1470.          would produce the same results as -I alone.
  1471.  
  1472.  
  1473.          -E[..]              (DFT, LFT)
  1474.          Specifies name(s)  (-Ename) or file with names (-E@namelist) of
  1475.          external or built-in functions. For LISP, this option is useful
  1476.          if  GNU-Emacs Lisp source code is scanned  to reduce the number
  1477.          of  undefined functions listed  in the  output file.  A list of
  1478.          GNU-EMACS (version  18.59) built-in functions is given with the
  1479.          file GNULISP.FCT. For DFT this option prevents output of built-
  1480.          in  functions/ keywords. An example  file with DBASE functions/
  1481.          procedures is provided with DBASE.FCT.
  1482.  
  1483.  
  1484.  
  1485.                                         24
  1486.  
  1487.  
  1488.  
  1489.          -F             (CFT, CST, DFT, FFT, LFT)
  1490.          Use  only ASCII characters for the call  tree output instead of
  1491.          the  DEFAULT semi graphic characters. This  option is useful if
  1492.          the generated  output file should be printed on a printer which
  1493.          does not  support semi graphic characters like they are defined
  1494.          in  the IBM character set.  It can also be  used to prepare the
  1495.          output file for use in a WINDOWS application like MicroEMACS if
  1496.          there is no font with semi graphics available.
  1497.  
  1498.          To view the semi graphic characters from the original output in
  1499.          Windows you have three choices:
  1500.  
  1501.          - select  a fixed size  font that supports  semi graphics (like
  1502.            Terminal)
  1503.          - open  SXT output file as 'MS-DOS text'  and select fixed size
  1504.            font (like Courier)
  1505.          - open SXT  output file from Windows Write and convert to Write
  1506.            format, then select fixed size font (like Courier)
  1507.  
  1508.  
  1509.          -G[name]       (CFT, CST, DFT, FFT, LFT)
  1510.          Generate a  database with the complete set of information about
  1511.          the  processed sources.  The additional parameter  'name' (path
  1512.          and  filename) is used  as an unique  base name for  the set of
  1513.          database  files (up to  6 significant  characters), the DEFAULT
  1514.          SXT  NAME ('CXT', 'DXT', ...) is used  if no name is specified.
  1515.          If 'name' ends with a (back-) slash, it is used as a path name.
  1516.          The  generated  database  files  (extension  '.DBF') are  dBASE
  1517.          compatible.  There are two  additional files  created, one with
  1518.          the command line options (extension '.CMD') and one with a list
  1519.          of  the source files (extension '.SRC')  being use for database
  1520.          generation.  They can be used as  command line definition files
  1521.          with '$' (command list) and '@' (file list).
  1522.  
  1523.          As  a result  of the  database generation  you will  find files
  1524.          named   'CXTxy.ext'   (or   other   SXT   names)   respectively
  1525.          'namexy.ext'  (user  defined  'name'), where  'x'  will  be 'F'
  1526.          (function)  for CFT, DFT,  FFT and  LFT or  'S' (structure) for
  1527.          CST,  'y' is replaced by  an internally used  character to mark
  1528.          the different database files and their contents.
  1529.  
  1530.  
  1531.          -H[elp]        (CFT, CST, DFT, FFT, LFT)
  1532.          See option -?.
  1533.  
  1534.  
  1535.          -HTML          (CFT, CST, DFT, FFT, LFT)
  1536.          This   option  generates   HTML  (HyperText   Markup  Language)
  1537.          compatible  output files with call  tree, cross reference, item
  1538.          name  index and filename index  which can be viewed  with a WWW
  1539.          (World  Wide  Web)  Browser  like  Netscape,  NCSA Mosaic,  MS-
  1540.          Internet  Explorer or  MS-WinWord Internet Assistant.  The HTML
  1541.          output is  done in parallel with the '.LST' output file, so all
  1542.          call  tree options  influence also  the  HTML output.  The HTML
  1543.          output    files   are    named   "prog.HTM",   "progNAMES.HTM",
  1544.          "progFILES.HTM" and "progXREF.HTM" (where 'prog' is one of CFT,
  1545.          CST, DFT, FFT or LFT).
  1546.  
  1547.  
  1548.                                         25
  1549.  
  1550.  
  1551.  
  1552.          Besides  the call  tree, cross reference,  item name  index and
  1553.          filename  index  information,  several  other  HTML  files  are
  1554.          generated  which provide additional functionality  based on the
  1555.          Netscape  2.0 extensions  for frames  and JavaScript.  The main
  1556.          entry to the HTML output is the file "progMAIN.HTM" (for 'prog'
  1557.          see above),  the file "progFRAME.HTM" which opens three frames,
  1558.          one  frame as a display window, one  frame with an alphabetical
  1559.          index   ("progINDEX.HTM")  and   another  frame   with  buttons
  1560.          ("progNAVIG.HTM")  to select  the information  being displayed.
  1561.          The  last   HTML  file  ("progCONT.HTM")  controls  the  output
  1562.          behaviour.
  1563.  
  1564.          Because the  HTML output files refer to each other by hypertext
  1565.          links  there  is  no  possibility  to  rename  them. To  handle
  1566.          multiple  sets  of  HTML output  files  copy  each  set  into a
  1567.          separate directory. To avoid unresolved links it is recommended
  1568.          that  options -a (and -u, if available)  are set to ensure that
  1569.          all items are listed. Note that national character sets are not
  1570.          handled properly. For additional information see HTML_RTF.DOC.
  1571.  
  1572.          For best viewing results with a WWW client, select a fixed-size
  1573.          font  e.g. Courier or  Courier New. The  SXT-HTML features were
  1574.          tested  with Netscape 2.02 (16bit, 32bit),  NCSA Mosaic for MS-
  1575.          Windows  v2.0  beta 4  and MS-WinWord  6.0a  Internet Assistant
  1576.          1.0Z. Tests  were also made with Mosaic and Netscape running on
  1577.          a SUN workstation. The best results were achieved with Netscape
  1578.          browsers  on  both  platforms,  because  Mosaic  seems to  have
  1579.          problems  with hypertext links in  local files. A  copy of NCSA
  1580.          Mosaic can be downloaded from 'ftp.ncsa.uiuc.edu', Netscape can
  1581.          be   found  at  'http://home.netscape.com'  and  the  Microsoft
  1582.          Internet Explorer  can be found at 'http://www.microsoft.com' /
  1583.          'ftp.microsoft.com'.
  1584.  
  1585.  
  1586.          -I[path]       (CFT, CST, FFT)
  1587.          This option enables the scanning of include files declared with
  1588.          '#include  "..."' or '#include <...>' or  with a similar syntax
  1589.          for  FORTRAN. The required path for the  include files is taken
  1590.          from  the INCLUDE  environment variable (DEFAULT  BEHAVIOUR) or
  1591.          can  be user defined by  'path'. Paths defined with  -I will be
  1592.          searched   before  any  other  paths   taken  from  environment
  1593.          variables  specified by -E or -P, so  care should be taken with
  1594.          that  option. Include  paths can  be  given either  absolute or
  1595.          relative. A  relative path is always considered relative to the
  1596.          directory  of  the source  file it  is  used with,  not  to the
  1597.          directory the  analysis is started from or the analysis program
  1598.          is located. For preprocessing (option -P) declaring -I* ignores
  1599.          missing  include files or errors with files  which could not be
  1600.          opened  due to compiler limits (message  'too many open files',
  1601.          see  chapter PROGRAM LIMITATIONS). This is  a 'quick and dirty'
  1602.          approach,  but   can  sometimes  be  useful,  if  include  file
  1603.          locations  are unknown  or  inaccessible. However,  the results
  1604.          will not be absolutely correct.
  1605.  
  1606.          Using the -I or -E option without -P allows the scanning of the
  1607.          source  file and the  included files  without preprocessing. In
  1608.          that  case an include file is handled  as if it were a complete
  1609.          new  file,  this can  lead to  errors  if a  file  inclusion is
  1610.  
  1611.                                         26
  1612.  
  1613.  
  1614.  
  1615.          specified  within a  function  or structure.  Also preprocessor
  1616.          controls  like  '#if ...'  are not  evaluated and  can  lead to
  1617.          unexpected  results.  Remember  this  especially  if you  place
  1618.          special comment sections enclosed in '#if 0 ... #endif' blocks.
  1619.  
  1620.  
  1621.          -Jcharset      (CFT, CST, DFT, FFT, LFT)
  1622.          Extend the  DEFAULT character for identifier recognition with a
  1623.          user  defined character set  'charset'. All  characters must be
  1624.          specified   within  one   -J  option.  The   following  default
  1625.          identifier character sets are used:
  1626.  
  1627.               C/C++ a-z A-Z 0-9 _$
  1628.               DBASE a-z A-Z 0-9 _
  1629.               FORTRAN a-z A-Z 0-9 _
  1630.               a-z A-Z 0-9 _$ (with option -$)
  1631.               LISP a-z A-Z 0-9 +-.*/<=>!?:$%_&~^
  1632.  
  1633.          This  option allows  the programmer  to use  national character
  1634.          sets  as they are common in Germany,  Denmark, Sweden and other
  1635.          European countries.
  1636.  
  1637.  
  1638.          -L[L][+]       (CFT, CST, DFT, FFT, LFT)
  1639.          Redirect  the screen output  to a file,  called 'CFT.LOG' resp.
  1640.          'CST.LOG'. If  '+' is set, the output is both written to screen
  1641.          and redirected  to the log file so that the output messages can
  1642.          both be  viewed as they appear and later analyzed. Finally, -LL
  1643.          resp. -LL+ appends the output to an existing log-file, this can
  1644.          be useful if CFT and CST are run from a batch-file to catch all
  1645.          output.
  1646.  
  1647.  
  1648.          -LIB[..]       (CFT)
  1649.          Specifies name(s) (-LIBname) or file with names (-LIB@namelist)
  1650.          of  library  functions.  Library functions  are  not  listed as
  1651.          undefined  functions  in  the  output  file  and  there are  no
  1652.          warnings  about  missing prototypes  or  missing  return types.
  1653.          Lists   of  C-library  functions  are   given  with  the  files
  1654.          MSVC15.FCT (MS Visual C++ 1.5) and GCC233.FCT (GNU-C 2.3.3).
  1655.  
  1656.  
  1657.          -M             (CFT, CST, FFT)
  1658.          This  option generates  a  source file/include  file dependency
  1659.          table for  every processed file. This table shows the dependent
  1660.          include files of a source file and can be used for a MAKE file.
  1661.          It is also useful to check if the included files are taken from
  1662.          the correct  directories. If a file is included more than once,
  1663.          the  number of  inclusions will  be  displayed. Note  that this
  1664.          option  will only work correctly if options  -P or -I are used,
  1665.          but not  on preprocessed files. There may also be problems with
  1666.          files  produced  by  source code  generators  like  LEX/FLEX or
  1667.          YACC/BISON.
  1668.  
  1669.  
  1670.          -N             (CFT, CST, DFT, FFT, LFT)
  1671.          Disable  the  writing of  an output  file. This  option  can be
  1672.          useful  if, for example, only a database  (option -G) should be
  1673.  
  1674.                                         27
  1675.  
  1676.  
  1677.  
  1678.          generated  with CFT or CST  and no output file  is required. In
  1679.          that  case the sometimes very time  consuming process of output
  1680.          file  writing is skipped. Note that for  CST the writing of the
  1681.          byte  offset file  "CST_OFFS.C" will  not  be affected  by this
  1682.          option.
  1683.  
  1684.  
  1685.          -NODIGRAPH     (CFT, CST)
  1686.          Disable  digraph translation during preprocessing (options -P).
  1687.          This  option  can  be  useful  for  processing  some  Microsoft
  1688.          specific  code,  because  the  Microsoft  specific 'based-code'
  1689.          operator  ':>' (introduced  with MS-C  6.0)  is also  a digraph
  1690.          which  translates to ']'. This  may lead in  some situations to
  1691.          'unbalanced brackets'.
  1692.  
  1693.  
  1694.          -NOINTR        (FFT)
  1695.          Do not recognize and display INTRINSIC functions in output call
  1696.          tree. Only subroutines and functions defined in the source code
  1697.          are displayed.
  1698.  
  1699.  
  1700.          -NOLIB         (CFT)
  1701.          Do  not display library  functions defined with  option -LIB in
  1702.          output call tree.
  1703.  
  1704.  
  1705.          -NOREPLACE     (CFT, CST)
  1706.          Disable  C++ keyword  replacing. This option  can be  useful if
  1707.          older C++ code with identifiers which are now recognized as new
  1708.          C++ keywords is processed (e.g. the keyword 'bitor' is replaced
  1709.          with '|').
  1710.  
  1711.  
  1712.          -NOUNSAFE (CFT, CST)
  1713.          This  option  warns  in  case  of  errors  with 'unsafe'  macro
  1714.          expansions  of the  integrated  preprocessor (option  -P) which
  1715.          otherwise   would  abort  execution  with   fatal  errors  (see
  1716.          PROBLEMS.DOC).  This is only  a 'work-around' that  can lead to
  1717.          following errors.
  1718.  
  1719.  
  1720.          -NOWARN72 (FFT)
  1721.          Do  not warn if characters are found  beyond column 72. FFT can
  1722.          process lines up to 132 columns length. By default a warning is
  1723.          given  if characters are  found beyond  column 72.  This can be
  1724.          disabled with this option.
  1725.  
  1726.  
  1727.          -O[..]              (CST)
  1728.          Specifies name(s)  (-Oname) or file with names (-O@namelist) of
  1729.          data  types for which the  calculation of structure/union sizes
  1730.          with byte  offset information for every data type member should
  1731.          be  performed. Additionally specifying -O+ sets  a flag for the
  1732.          recursive  collection of sub-structures  during expansion which
  1733.          are displayed without specifying them by -O. This means that if
  1734.          a structure/union consists of members which are also structures
  1735.          or unions (and so on), it is not necessary to specify all these
  1736.  
  1737.                                         28
  1738.  
  1739.  
  1740.  
  1741.          data  type  names  with  -O  to  enable  them  for byte  offset
  1742.          calculation.  Instead, you  have to specify  only the  top most
  1743.          data  type with  -Oname and  additionally -O+  to force  CST to
  1744.          select all  related sub-types for displaying. If -O+ is set but
  1745.          NO names  are specified, ALL structures and unions will be used
  1746.          for  byte offset calculations  (the resulting file  can be very
  1747.          big)!
  1748.  
  1749.          As  the result of this  option, CST generates a  C source file,
  1750.          called 'CST_OFFS.C'. This file needs some additional editing to
  1751.          declare necessary include files, data types, defines or pragmas
  1752.          before  it can be  compiled with the  C compiler  for which the
  1753.          file  was generated (be  sure to  use the  same includes!). The
  1754.          resulting  executable prints  for every  structure/union member
  1755.          the   byte   offset   relative   to   the   beginning  of   the
  1756.          structure/union (decimal  and hexadecimal) and the size of each
  1757.          member, the resulting structure/union size and also information
  1758.          whether  a structure/union member has  been aligned (= compiler
  1759.          dependent insertion of fill bytes before that member) or if the
  1760.          structure/union was  padded with fill bytes at the end of it to
  1761.          align the size to a specific length.
  1762.  
  1763.          To   get  these  information  and   to  perform  the  necessary
  1764.          calculations therefore, the source file 'CST_OFFS.C' can become
  1765.          very   large  and  makes   use  of  the   C  macro  programming
  1766.          capabilities,  which  may lead  in  some rare  cases  to errors
  1767.          during the  compilation due to the internal limitations of some
  1768.          C compilers.
  1769.  
  1770.          The  -O option is very useful if  you need detailed information
  1771.          about   structures/unions  in  case  of   error  searching  and
  1772.          debugging, especially for hardware debugging with an ICE. It is
  1773.          also  useful for  finding out the  differences in  the internal
  1774.          layout  of a structure/union  in the  case of  porting C source
  1775.          code between different compilers and/or operating systems or if
  1776.          data   structures  are  exchanged  between  different  hardware
  1777.          platforms, for  example with data communication. You can verify
  1778.          if  the  expected  structure/union layout  and  size  is really
  1779.          produced by the target compiler.
  1780.  
  1781.  
  1782.          -P[name]       (CFT, CST)
  1783.          Run the integrated C preprocessor before the file scan. In this
  1784.          case  the include  path is taken  from the  INCLUDE environment
  1785.          variable  (DEFAULT  BEHAVIOUR), from  the  user  defined 'name'
  1786.          environment  and additional  paths from  -I  and -E  option are
  1787.          used.  If special paths  should be searched  before the default
  1788.          paths,  they  must  be  specified by  the  -I  path  or  the -E
  1789.          environment option  and they must be placed on the command line
  1790.          before  the  -P  option  to  be  processed  first.  The -D,  -U
  1791.          preprocessor  defines and -T type and memory  model and -B size
  1792.          information  are  also  used,  if  defined.  The  path for  the
  1793.          preprocessor  output file  can be specified  by the  -v option,
  1794.          otherwise  the current working directory  will be used (DEFAULT
  1795.          BEHAVIOUR). If option -C++ is set, the macro '__cplusplus' will
  1796.          be predefined before preprocessing to enable C++ macros and C++
  1797.          comment recognition.
  1798.  
  1799.  
  1800.                                         29
  1801.  
  1802.  
  1803.  
  1804.          If  a fatal error occurs during  preprocessing, the analysis of
  1805.          the file will be aborted and the next file in the queue will be
  1806.          processed  (if 'out of memory' occurs  the complete analysis is
  1807.          aborted!). For a description of the error format see option -W.
  1808.  
  1809.          If  you are using a compiler which  is not supported by CFT and
  1810.          CST  or the build-in  preprocessing doesn't  satisfy your needs
  1811.          because   the   results  seem   to  be   different   from  your
  1812.          preprocessor, you  can preprocess the files you want to analyze
  1813.          with your own preprocessor and use these files as input for CFT
  1814.          and CST. To ensure that the filename and line number references
  1815.          are  valid your preprocessor must  insert #line directives into
  1816.          the source.
  1817.  
  1818.          Preprocessing  with another compiler  can also  be necessary if
  1819.          the integrated preprocessor has problems with your source, e.g.
  1820.          because  the nesting level for  include files is  too high (see
  1821.          section   PROGRAM  LIMITATIONS)  or  it   aborts  during  macro
  1822.          expansions (see PROBLEMS.DOC).
  1823.  
  1824.  
  1825.          -Q[..]              (CFT, CST, DFT, FFT, LFT)
  1826.          Specify   the  name   (-Qname)  or  a   file  with   the  names
  1827.          (-Q@namelist)   of   those  source   files   for   which  their
  1828.          functions/data  types should be listed in  the output call tree
  1829.          file  (sorted by line  numbers). The  files are  handled in the
  1830.          given -Q  sequence. If additional -S options are specified, the
  1831.          -S items will be listed after all -Q options are done.
  1832.  
  1833.  
  1834.          -R             (CFT, CST, DFT, FFT, LFT)
  1835.          By  default, CFT and CST  generate the hierarchy  tree chart of
  1836.          the  called function/data type  ("CALLER:CALLEE relation", "WHO
  1837.          CALLES  WHOM").  The  -R option  produces  an  inverted listing
  1838.          showing  the  callers/users  of  each  function/data  type.  It
  1839.          generates the output as the function/data type hierarchy member
  1840.          list tree  chart in reverse order as a list of calling items of
  1841.          the  referenced basic  item ("CALLEE:CALLER relation",  "WHO IS
  1842.          CALLED  BY WHOM"). This option  is useful to  get the relations
  1843.          between functions/data types and their callers/users.
  1844.  
  1845.  
  1846.          -RATIONAL      (CFT, CST, DFT, FFT, LFT)
  1847.          This option generates so called 'Petal' files for Rational Rose
  1848.          (Windows),  a  CASE-tool supporting  the  Booch Object-Oriented
  1849.          Analysis  and Design (OOAD) method.  The generated output files
  1850.          can   be  imported  by  Rational  Rose   to  use  the  built-in
  1851.          capabilities  for visualization,  but in  the  case of  the SXT
  1852.          programs  (mis-)  used  to  graphically  visualize the  calling
  1853.          relationships  of  functions resp.  data  types.  The -RATIONAL
  1854.          option  is  a  work-around  for  the  missing graphical  layout
  1855.          capabilities  of  the  SXT  programs  (which  some  users  have
  1856.          requested  in the past) by using an  external program for doing
  1857.          the missing features.
  1858.  
  1859.          Two different types of description files are generated, one for
  1860.          class diagrams and one for finite state machine (FSM) diagrams.
  1861.          The class  diagram files are named 'prog.PTL' and the FSM files
  1862.  
  1863.                                         30
  1864.  
  1865.  
  1866.  
  1867.          'prog_FSM.PTL' with 'prog' as the name of the SXT program being
  1868.          used.  CST generates two additional  files named 'CSTCLASS.PTL'
  1869.          and    'CSTCLFSM.PTL'   describing    the   class   inheritance
  1870.          relationships  in  the same  way.  In the  class  diagrams, for
  1871.          functions  (CFT, DFT, FFT, LFT)  the USES-relationship was used
  1872.          to  display the calling relationships  (the classes are misused
  1873.          as   functions),  whereas  for  data   types  and  classes  the
  1874.          INHERITANCE-relationship is used.
  1875.  
  1876.          If  you have Rational Rose,  you have to  perform the following
  1877.          steps to  get impressive results: Start Rational Rose, select a
  1878.          new  model  ('File'  - 'New')  and  import  the  generated file
  1879.          ('File'  - 'Import...'). If  you imported a  FSM description, a
  1880.          class  diagram with  one class  symbol named  'CallGraph' (FSM)
  1881.          appears.  Click on  that symbol  and  choose 'Browse'  - 'State
  1882.          Diagram'.  Now select  'Tools' - 'Layout'  to start  the layout
  1883.          optimization function. As the result the graphical call tree of
  1884.          the  source code analysis is  displayed with each function/data
  1885.          type  shown as  a circle  ('state')  and the  call relationship
  1886.          shown  as  an arrow  ('transaction')  from the  calling  to the
  1887.          called  item, for classes from the  superclass to the subclass.
  1888.          You can zoom into the diagram, print the results or incorporate
  1889.          the  diagrams into  your  program documentation  via Clipboard,
  1890.          e.g. into Word for Windows.
  1891.  
  1892.          In case  of a class description file, a class category with one
  1893.          category  named  'Program' appears  after  file  import. Double
  1894.          click  on that symbol to open the  associated class diagram and
  1895.          activate the  layout function. As the result the graphical call
  1896.          tree  of  the  source  code  analysis  is  displayed with  each
  1897.          function shown  as a class and the call relationship shown as a
  1898.          double line from the calling (circle) to the called function.
  1899.  
  1900.          NOTE: The  SXT programs cannot generate input for Rational Rose
  1901.          comparable  to that generated  by the C++  analyzer of Rational
  1902.          Rose, SXT just uses Rational Rose's printing capabilities!
  1903.  
  1904.          The  -RATIONAL  option  was tested  with  the  Beta  version of
  1905.          Rational  Rose/C++ (Windows) 2.0.  If you  get warnings reading
  1906.          the files with an earlier (later) version of Rational Rose edit
  1907.          the  file and  reduce (increase) this  value. The  SXT programs
  1908.          currently set this value 35 for version 2.5. Note that Rational
  1909.          Rose  needs even for small and medium  sized projects some time
  1910.          to import  the file and process the diagram layout. There is no
  1911.          guarantee that this will always be successful.
  1912.  
  1913.          Rational  Rose is  a commercial  product, for  more information
  1914.          contact Rational directly at
  1915.  
  1916.              Rational, 2800 San Tomas Expressway, Santa Clara,
  1917.              CA 95051-0951, U.S.A.
  1918.          or
  1919.              Rational GmbH, Rosenstr. 7, Grosshesselohe, D-82049 Pullach
  1920.              im Isartal, Germany
  1921.  
  1922.  
  1923.  
  1924.  
  1925.  
  1926.                                         31
  1927.  
  1928.  
  1929.  
  1930.          -RTF[x]        (CFT, CST, DFT, FFT, LFT)
  1931.          This option  generates a RTF (Rich Text Format) compatible call
  1932.          tree and file contents list output file. The RTF output file is
  1933.          named "prog.RTF"  (where 'prog' is one of CFT, CST, DFT, FFT or
  1934.          LFT)  by default unless the  optional extension 'x'  is used to
  1935.          specify  another filename. The  RTF output is  done in parallel
  1936.          with the '.LST' output file, so all call tree options influence
  1937.          also  the RTF  output. The  RTF file  can  be imported  by word
  1938.          processors  which  can  handle  RTF  (e.g.  Word for  Windows).
  1939.          Another  very useful feature  is the possibility  to generate a
  1940.          Windows  Help file  from the RTF  output. This  can be  done by
  1941.          using the Microsoft Windows Help Compiler HC.EXE resp. HC31.EXE
  1942.          (or  via the HC.BAT  batch file)  which compiles  the .RTF file
  1943.          into a .HLP file (e.g. 'hc31 cft.rtf' generates cft.hlp). There
  1944.          will  also be a  Windows Help compiler  project file generated,
  1945.          which can  be used for RTF file compilation with compression to
  1946.          reduce  the  resulting help  file  size. The  command  is 'hc31
  1947.          cft.hpj'.  The help  file can  be  viewed with  WINHELP.EXE. It
  1948.          contains  a  searchable sorted  list of  all  items (functions,
  1949.          types),  a   file  contents  list  and  a  caller/callee  cross
  1950.          reference list. Similar to the HTML output, hypertext links are
  1951.          embedded  which  allow  jumps  within  the  help  file to  item
  1952.          definitions.  To avoid unresolved links  it is recommended that
  1953.          options  -a (and -u, if  available) are set to  ensure that all
  1954.          items are listed. For additional information see HTML_RTF.DOC.
  1955.  
  1956.  
  1957.          -S[..]              (CFT, CST, DFT, FFT, LFT)
  1958.          Specify  name  (-Sname)  or file  with  names  (-S@namelist) of
  1959.          functions/data  types  to search  for  and to  dump  if present
  1960.          (names are  case sensitive). Only these items are listed in the
  1961.          output  call tree file, all  others are ignored.  The items are
  1962.          listed  in the given -S  sequence. If also all  the other items
  1963.          not covered by -S should be listed, the user can specify -S+ on
  1964.          the command  line. The '+' parameter forces all remaining items
  1965.          to be printed after all the -S items have been printed. For DFT
  1966.          and FFT the item names are considered uppercase. By using -S on
  1967.          the command  line, it is necessary to surround a data type name
  1968.          that  consists of  two words with  double quotation  marks like
  1969.          "struct _iobuf" to connect the two words. This is not necessary
  1970.          inside  a list file, but  there every search name  must be on a
  1971.          separate line.
  1972.  
  1973.  
  1974.          -TAGS[x]       (CFT, CST, DFT, FFT, LFT)
  1975.          This option  generates a TAGS file with information for VI-like
  1976.          tagging  of defined identifiers. The TAGS  file is named "TAGS"
  1977.          by default unless the optional extension 'x' is used to specify
  1978.          another filename. Each entry in the TAGS file has the format
  1979.  
  1980.               identifier<tab>file<tab>vi-search-pattern
  1981.  
  1982.          where  'vi-search-pattern' is the  line number  in 'file' where
  1983.          'identifier'  is defined. As using  the line number  is a usual
  1984.          practice  if 'typedef' definitions  are included  into the TAGS
  1985.          file  this should be no problem. The  generated TAGS files were
  1986.          successful  tested with the MSDOS versions  of VI (from Mortice
  1987.          Kern  Systems Inc.) and  the public domain  VI-clone ELVIS, but
  1988.  
  1989.                                         32
  1990.  
  1991.  
  1992.  
  1993.          should  also work with  other VI versions.  Since VI originates
  1994.          from  UNIX, the TAGS file contains only  LF, not CR+LF, as line
  1995.          ending. I have done it this way to avoid possible problems with
  1996.          close-to-UNIX VI  ports, but this may also lead to new problems
  1997.          if  CR+LF is really needed.  To change from DOS  to UNIX styles
  1998.          and vice versa tools like DOS2UNIX or UNIX2DOS can be used. See
  1999.          also option -CTAGS for additional information.
  2000.  
  2001.  
  2002.          -Tn            (FFT)
  2003.          Set   the  tabulator   expansion  size   to  'n'   (DEFAULT:  8
  2004.          characters).
  2005.  
  2006.  
  2007.          -Ttype,m       (CFT, CST)
  2008.          Use  this  option to  set  the compiler  type  for  source code
  2009.          preprocessing to one of the following types:
  2010.  
  2011.               MSC51 Microsoft C 5.1
  2012.               MSC70 Microsoft C/C++ 7.0
  2013.               MSVC15 Microsoft Visual C++ 1.5
  2014.               MSVC22 Microsoft Visual C++ 2.2
  2015.               MSVC40 Microsoft Visual C++ 4.0
  2016.               MSVC41 Microsoft Visual C++ 4.1
  2017.               MSVC42 Microsoft Visual C++ 4.2
  2018.               TC10 Borland Turbo C++ 1.0
  2019.               BC20 Borland C++ 2.0
  2020.               BC31 Borland C++ 3.1
  2021.               BC10OS2 Borland C++ 1.0 for OS/2
  2022.               WATCOMC100 Watcom C/C++ 10.0a
  2023.               GNUC222 GNU-C 2.2.2
  2024.               GNUC263 GNU-C 2.6.3
  2025.               GNUC272 GNU-C 2.7.2
  2026.               I960 Intel 80960 iC960 3.0
  2027.  
  2028.          The  supported memory models are T(iny)  (valid only for MSC70,
  2029.          MSVC15,   TC10,  BC20,  BC31),  S(mall),  M(edium),  C(ompact),
  2030.          L(arge),  H(uge),  'L' is  assumed as  default if  no  model is
  2031.          specified. MS Visual C++ 2.2 / 4.0 / 4.1 / 4.2, Borland C++ for
  2032.          OS/2, GNU-C  and Intel iC960 do not need a memory model because
  2033.          they  compile  really 32  bit  code. The  Intel  iC960 compiler
  2034.          requires   the   definition  of   the   80960   RISC  processor
  2035.          architecture which is one of KA, KB, SA, SB, MC, CA (default is
  2036.          KB). For  the Watcom C/C++ compiler there are no memory options
  2037.          predefined due  to the wide range of possible targets, the user
  2038.          has to specify the necessary options with -B and -D.
  2039.  
  2040.          This  option  causes  several  compiler  dependent preprocessor
  2041.          macros (if they were known to me, however) to be defined before
  2042.          preprocessing starts.  This option can only be used with the -P
  2043.          option, otherwise it has no effect.
  2044.  
  2045.          If  your  compiler  is  not  supported,  you  can  perform  the
  2046.          following  steps:  Find  out  which  preprocessor  defines  are
  2047.          necessary (manual,  help file) and declare them with option -D,
  2048.          then  declare,  depending  on  the  selected  memory  model  or
  2049.          processor architecture, the type sizes with option -B.
  2050.  
  2051.  
  2052.                                         33
  2053.  
  2054.  
  2055.  
  2056.  
  2057.          -U[..]              (CFT, CST)
  2058.          Specifies  a  predefined  macro  name  (-Dname)  or  file  with
  2059.          predefined  macro  names  (-U@namelist)  to  be  undefined  for
  2060.          preprocessing.  Note that  the  default predefined  macro names
  2061.          '__FILE__',   '__LINE__',  '__DATE__',   '__TIME__'  cannot  be
  2062.          undefined. All  other predefined names for the various compiler
  2063.          types  can be undefined. Like for -D,  the names are considered
  2064.          case-sensitive,  but  trigraph or  digraph  translation  is not
  2065.          performed  because the  internal representation  cannot contain
  2066.          them.
  2067.  
  2068.  
  2069.          -V             (CFT)
  2070.          List prototyped  functions which are neither called nor defined
  2071.          (option  -a  and -u).  This  option is  useful  to  find unused
  2072.          function  prototypes which could  be probably  removed from the
  2073.          source code.
  2074.  
  2075.  
  2076.          -Wlevel        (CFT, CST, DFT, FFT, LFT)
  2077.          Set  error  and warning  message level.  Higher  warning levels
  2078.          include  lower ones.  The DEFAULT level  is always  the highest
  2079.          supported warning level, possible levels are:
  2080.  
  2081.          0 :    all  error and  warning  messages are  suppressed except
  2082.                 fatal errors,
  2083.          1 :    display serious errors or warnings,
  2084.          2 :    includes level 1 plus additional errors and warnings,
  2085.          3 :    includes level 2 plus errors/warnings/remarks,
  2086.          4 :    includes  level 3 plus warnings  about implicit declared
  2087.                 functions and lacks of type or storage class.
  2088.  
  2089.          The following levels affect only preprocessing (CFT and CST):
  2090.  
  2091.          5 :    includes  level   4  plus  warnings  and  errors  during
  2092.                 preprocessing  (non-fatal  errors  and  warnings  during
  2093.                 preprocessing are  otherwise not displayed, preprocessor
  2094.                 is running in 'silent mode'),
  2095.          6 :    includes  level  5 plus  remarks/slight  warnings during
  2096.                 preprocessing.
  2097.  
  2098.          The output format for messages during file scan is
  2099.  
  2100.               filename(line): error: description
  2101.               filename(line): warning: description
  2102.  
  2103.          and during preprocessing (warning levels 5 and 6)
  2104.  
  2105.               preprocessor:  filename(line):  error:  description source
  2106.          line
  2107.               preprocessor:  filename(line): warning: description source
  2108.          line
  2109.  
  2110.  
  2111.  
  2112.  
  2113.  
  2114.  
  2115.                                         34
  2116.  
  2117.  
  2118.  
  2119.          -XLAMBDA       (LFT)
  2120.          Recognize  the LISP resp.  SCHEME keyword  'lambda' for unnamed
  2121.          function  declarations. By  DEFAULT, 'lambda'  is treated  as a
  2122.          simple identifier.
  2123.  
  2124.  
  2125.          -XSCHEME       (LFT)
  2126.          Assume   SCHEME  source  code  instead   of  LISP  source  code
  2127.          (DEFAULT).  This  means that  functions are  recognized  by the
  2128.          'define' SCHEME keyword instead of the 'defun' resp. 'defmacro'
  2129.          LISP keywords.
  2130.  
  2131.  
  2132.          -Z[s]               (CFT, CST, DFT, FFT, LFT)
  2133.          Display  every caller and  member for  each function/data type,
  2134.          's'   sorts   by   the   number   of   calls  (DEFAULT   ORDER:
  2135.          lexicographical),  this is an extension of  the -c option. This
  2136.          option shows the relations in the following form:
  2137.  
  2138.               List of parent functions/data types:
  2139.               1. caller (reference #) <# of calls from>
  2140.               ...
  2141.               n. caller ...
  2142.          function/data type (reference #) <# of calls from parents, # of
  2143.          calls to children>
  2144.               List of child functions/data types:
  2145.               1. called member (reference #) <# of calls to>
  2146.               ...
  2147.               m. called member ...
  2148.  
  2149.          This compact form lists all callers and members with the number
  2150.          of  their calls,  recursions are  detected and  displayed. Note
  2151.          that this  option can be extremely time consuming if the number
  2152.          of source files is very large!
  2153.  
  2154.  
  2155.          -a             (CFT, CST, DFT, FFT, LFT)
  2156.          List  every  function/data  type,  also  previously  referenced
  2157.          functions/data  types. This generates a  complete list of every
  2158.          function/data type  in lexicographical order with references to
  2159.          their first location.
  2160.  
  2161.  
  2162.          -b             (CST)
  2163.          Display  the C++  class inheritance relationships.  This option
  2164.          generates two listings. The first one displays the complete C++
  2165.          class  hierarchy graph(s). The second one  shows for each class
  2166.          first  the superclasses from  which the class  inherits and the
  2167.          access  restrictions  (public,  protected,  virtual,  ...)  and
  2168.          second the  subclasses which inherit from the given class, also
  2169.          with  access restrictions.  This option is  useful to  find out
  2170.          things like the class dependencies or multiple inheritance.
  2171.  
  2172.  
  2173.          -b             (FFT)
  2174.          Handle backslash in FORTRAN character constant (DEFAULT is NO).
  2175.          This  option  is  useful  if  non-standard UNIX-like  character
  2176.          constants with backslash escape sequences (e.g. '\'') are used,
  2177.  
  2178.                                         35
  2179.  
  2180.  
  2181.  
  2182.          which  are not handled  by default  and will  therefore lead to
  2183.          errors.
  2184.  
  2185.  
  2186.          -c[s]               (CFT, CST, DFT, FFT, LFT)
  2187.          Display  the number  of calls to  each function/data  type, 's'
  2188.          sorts by  the number of calls (DEFAULT ORDER: lexicographical).
  2189.          Useful  to  find  out  which  functions/data  types  are  never
  2190.          called/used  (maybe unnecessary and  can be  deleted) and which
  2191.          ones  are   the  most  frequently  called/used  (together  with
  2192.          profiler  results a subject for  further optimization efforts).
  2193.          For FFT see also the description for option -CALL.
  2194.  
  2195.  
  2196.          -charwarn      (CFT, CST, DFT, FFT, LFT)
  2197.          Warning  if unknown/illegal characters are  found in the source
  2198.          code  during analysis. By  default, there  is no  now no longer
  2199.          such a warning.
  2200.  
  2201.  
  2202.          -cmdline       (CFT, CST, DFT, FFT, LFT)
  2203.          Print  the command line options at the  beginning of the output
  2204.          file as a remark for the generation rules for that output file.
  2205.          All  options and files  specified on  the command  line, in the
  2206.          environment variable,  the command list and the file list files
  2207.          are listed.
  2208.  
  2209.  
  2210.          -defmacro      (LFT)
  2211.          Recognize the 'defmacro' keyword in SCHEME source code.
  2212.  
  2213.  
  2214.          -dn            (CFT, CST, DFT, FFT, LFT)
  2215.          Set  the  maximum  function/structure/union  nesting  level for
  2216.          output generation to 'n' (DEFAULT: maximum value n = 999). This
  2217.          means  that the request for  displaying a deeper  level will be
  2218.          rejected  and the  output call  tree will  be truncated  at the
  2219.          given level.
  2220.  
  2221.  
  2222.          -e[char]       (CFT, CST, DFT, FFT, LFT)
  2223.          Generate  formatted ASCII  text  files with  function/data type
  2224.          list  and file list. All entries are  separated by the optional
  2225.          'char'  character, if  'char '  is  not defined,  the tabulator
  2226.          character is used as DEFAULT SEPARATOR. If spaces are wanted as
  2227.          separating  characters, you have to write  -e" ". Such prepared
  2228.          files can be used directly as input to other programs like word
  2229.          processors   (e.g.   MS-WORD   for   WINDOWS)   or  spreadsheet
  2230.          calculators  (e.g.  MS-EXCEL),  for  example  for documentation
  2231.          purposes. The following files are created:
  2232.  
  2233.          CFTITEMS.TXT:
  2234.          Contents: function name, return type, filename, line #, total #
  2235.          of  function bytes, # of function comment  bytes, # of function
  2236.          lines, # of control statements, # of brace levels
  2237.  
  2238.          CSTITEMS.TXT:
  2239.          Contents: data type name, filename line #
  2240.  
  2241.                                         36
  2242.  
  2243.  
  2244.  
  2245.  
  2246.          CFTFILES.TXT and CSTFILES.TXT:
  2247.          Contents:  filename,  # of  lines,  file size  in  bytes,  # of
  2248.          comment bytes, # of functions/ data types
  2249.  
  2250.  
  2251.          -f             (CFT, CST, DFT, FFT, LFT)
  2252.          Generate an  output list in short form, only with the function/
  2253.          data  type  names,  no  further  description  of  the  internal
  2254.          function/ data type elements.
  2255.  
  2256.  
  2257.          -filetree      (CFT, CST, FFT)
  2258.          This  option displays the file hierarchy  tree for every source
  2259.          file.  The look of  the file hierarchy  tree is  similar to the
  2260.          function  hierarchy tree. Unless option  -M displays the 'flat'
  2261.          source  vs. include  file relationship,  this option  shows the
  2262.          real  nested  source  file include  file  hierarchy  tree. This
  2263.          option  is useful to see how the  files are related and nested.
  2264.          Note that this option will only work correctly if options -P or
  2265.          -I  are used, but not on preprocessed  files. There may also be
  2266.          problems  with files  produced by  source code  generators like
  2267.          LEX/FLEX or YACC/BISON.
  2268.  
  2269.  
  2270.          -g[name]       (CFT, CST, DFT, FFT, LFT)
  2271.          Read  a  previously  generated database  (see  option  -G). The
  2272.          additional  parameter 'name' (path and filename)  is used as an
  2273.          unique  base  name for  the  set  of database  files  (up  to 6
  2274.          significant  characters), the DEFAULT NAME 'CXT'  is used if no
  2275.          name  is specified. If 'name' ends with  a (back-) slash, it is
  2276.          used  as a  path name.  Every source  file  will be  tested for
  2277.          changes  of  file creation  time and  file size  and  a warning
  2278.          message  will be given to inform the  user. It is currently not
  2279.          possible to update the results of such files.
  2280.  
  2281.  
  2282.          -h[elp]        (CFT, CST, DFT, FFT, LFT)
  2283.          See option -?.
  2284.  
  2285.  
  2286.          -iname         (CFT, DFT, FFT, LFT)
  2287.          Ignore function  member 'name' in output call tree. It will not
  2288.          be displayed and will be skipped instead if found as a function
  2289.          member.  For   DFT  and  FFT  the  item  names  are  considered
  2290.          uppercase. This option can be useful if, for example, functions
  2291.          are used  only for test purposes and are of no further interest
  2292.          for the  user and should be ignored in the output call tree. It
  2293.          is  also  possible to  specify  library functions  so  that the
  2294.          output call tree contains only user defined functions.
  2295.  
  2296.  
  2297.          -l[1]               (CFT, DFT, FFT, LFT)
  2298.          Option  -l lists every  called function inside  a function body
  2299.          only  once  in  case of  repeated  consecutive  calls (DEFAULT:
  2300.          display  every occurrence). If  a function is  called more than
  2301.          once without  any other call in between, there will be only one
  2302.          reference of that function call in the output call tree. Option
  2303.  
  2304.                                         37
  2305.  
  2306.  
  2307.  
  2308.          -l1 lists  every called function inside a function body exactly
  2309.          once.  This option results in shorter output  files and gives a
  2310.          general overview.
  2311.  
  2312.  
  2313.          -mtype         (CST)
  2314.          Start the  data type tree chart with data type 'type' (-mtype).
  2315.          If  -m+ is specified, the  output starts with  the topmost data
  2316.          type,  this is the data  type which is in  the highest level of
  2317.          the   hierarchy   tree  chart.   The  default   output   is  in
  2318.          lexicographical order  of the displayed data types. Useful if a
  2319.          selected  structure/union should be displayed  at the beginning
  2320.          of the output file.
  2321.  
  2322.  
  2323.          -m[name]       (CFT, FFT)
  2324.          -mname         (DFT, LFT)
  2325.          Start  the function  call tree dump  with function  'main' (CFT
  2326.          -m),  'PROGRAM'  (FFT  -m) or  'name'  (-mname),  name  is case
  2327.          sensitive.  If -m+  is specified,  the  output starts  with the
  2328.          topmost function,  this is the function which is in the highest
  2329.          level  of the hierarchy call  tree. If this option  is not set,
  2330.          the   default  is   lexicographical  order  of   the  displayed
  2331.          functions.
  2332.  
  2333.          Usually, the  complete function call tree should start with the
  2334.          'main' function so that every subfunction is a (sub-) member of
  2335.          'main'. This option is useful for windows programs to start the
  2336.          output with  the initial 'WinMain' function (-mWinMain) instead
  2337.          of  'main'. It can  also be used  to start the  output with the
  2338.          initial  assembler  start-up  code  being  executed before  the
  2339.          'main'-function is called.
  2340.  
  2341.  
  2342.          -n[a]               (CFT, CST, DFT, FFT, LFT)
  2343.          Display  the  most  critical  function  call path  respectively
  2344.          display  the  data  structure/union  with  the maximum  nesting
  2345.          level.   The  modificator   'a'  is   used  to   display  every
  2346.          function/structure  with  its  users/callers  (DEFAULT: display
  2347.          only  deepest call  path). This option  helps to  determine the
  2348.          complexity  of the  function call/data structure  hierarchy and
  2349.          finds  recursions over  several call/nesting levels.  Note that
  2350.          for  functions the  maximum call  path  being displayed  is the
  2351.          result  of  the  static source  code  analysis.  During program
  2352.          execution  the call path  can be  even deeper  if functions are
  2353.          called indirectly with function pointers or similar mechanisms.
  2354.  
  2355.  
  2356.          -noundef       (CFT, DFT, FFT, LFT)
  2357.          Ignore undefined  items (functions, subroutines) in output call
  2358.          tree.  Display  only  those which  are  really  defined  in the
  2359.          analyzed source code.
  2360.  
  2361.  
  2362.          -ofile              (CFT, CST, DFT, FFT, LFT)
  2363.          Write  the generated analysis  results to  file 'file'. DEFAULT
  2364.          BEHAVIOUR:  The filenames are  'CFT.LST' for  CFT and 'CST.LST'
  2365.          for  CST. Possible overwriting of an  existing output file with
  2366.  
  2367.                                         38
  2368.  
  2369.  
  2370.  
  2371.          the  same name other than the default  one will be detected and
  2372.          prompted for user reconfirming. The resulting output file is an
  2373.          ASCII  text file  with no  formatting  characters which  can be
  2374.          printed  with every  printer, viewed  and/or edited  with every
  2375.          text editor  and taken as input to word processors, for example
  2376.          for documentation purposes.
  2377.  
  2378.  
  2379.          -qn            (FFT)
  2380.          Set  the  number  of continuation  lines  to  'n'  (DEFAULT: 19
  2381.          lines). The number must be in the range from 0 to 99.
  2382.  
  2383.  
  2384.          -time               (CFT, CST, DFT, FFT, LFT)
  2385.          Print  runtime information about the  times consumed for source
  2386.          analysis,  preprocessing,  output  dump,  database  reading and
  2387.          writing  and for other miscellaneous jobs  plus the total time.
  2388.          The results are given in the format MINUTE:SECOND.MILLISECOND.
  2389.  
  2390.  
  2391.          -touch         (CFT, CST, DFT, FFT, LFT)
  2392.          If the  file information in a database concerning the file date
  2393.          and  the file size  is out-of-date, it  will be  updated if the
  2394.          database  is read (option -g) and option  -touch is set. Useful
  2395.          to avoid the warnings e.g. with the BRIEF macros. However, this
  2396.          option  should  only be  used if  the contents  of  the related
  2397.          source  files has not  changed. This option  does not reprocess
  2398.          and analyze the related sources, there will be no update of the
  2399.          results!
  2400.  
  2401.  
  2402.          -u             (CFT, DFT, FFT, LFT)
  2403.          List undefined  functions. These functions are probably library
  2404.          functions,  defined in other files which  have not been scanned
  2405.          or are unresolved externals found by the linker.
  2406.  
  2407.  
  2408.          -vpath         (CFT, CST, FFT)
  2409.          Set  a specific  path for  the intermediate  precompiler output
  2410.          file.  'path' can be  a path name  or a drive  letter with path
  2411.          name, e.g.  'c:\tmp' or 'g:\' (not 'g:' without '\', this is an
  2412.          error). This  option is useful to speed up execution speed when
  2413.          the intermediate  file can be stored on a RAM-disk so that file
  2414.          access  to the precompiled file  is much faster than  on a hard
  2415.          disk.  Tests have shown that  the analysis time  can be reduced
  2416.          for  more than 25%. Environment variables  like 'TMP' or 'TEMP'
  2417.          to set the path for temporary files are not evaluated.
  2418.  
  2419.  
  2420.          -y             (CFT, CST, DFT, FFT, LFT)
  2421.          Display cross  link list of files which contain referencing and
  2422.          referenced  functions/data types  of functions/data types  of a
  2423.          specific file. This option shows the relations in the following
  2424.          form:
  2425.  
  2426.               1. referencing file
  2427.               ...
  2428.               n. referencing file
  2429.  
  2430.                                         39
  2431.  
  2432.  
  2433.  
  2434.          file
  2435.               1. referenced file
  2436.               ...
  2437.               m. referenced file
  2438.  
  2439.          This  option  is  useful  if you  want  to  find  out  the file
  2440.          relationships. This information can be used to isolate specific
  2441.          files from  a project, e.g. library files. It is also useful if
  2442.          you  want to separate a  function and want to  know which other
  2443.          files  are needed because  they contain  called functions. Note
  2444.          that  there may be problems with files  produced by source code
  2445.          generators like LEX/FLEX or YACC/BISON.
  2446.  
  2447.  
  2448.          -z             (CFT, CST, DFT, FFT, LFT)
  2449.          Generate  a function/data type call  cross reference table. For
  2450.          every function/data  type the location of its definition (file,
  2451.          line)  and a complete  list of its  calls/references, sorted by
  2452.          files and line numbers is given in the following form:
  2453.  
  2454.          1. function/data type (reference #) [file #], line #
  2455.               [file #]: line #, ...
  2456.               ...
  2457.  
  2458.          2. ...
  2459.               ...
  2460.  
  2461.          The  functions/data  types  are  displayed  in  lexicographical
  2462.          order.  At the end of  the section is the  cross reference file
  2463.          list. Note  that this option can be extremely time consuming if
  2464.          the number of source files is very large!
  2465.  
  2466.  
  2467.          -$             (FFT)
  2468.          Recognize  $ as identifier character,  not as delimiter. Useful
  2469.          for source code written for VAX (VMS)- or IBM (MVS)-Fortran.
  2470.  
  2471.  
  2472.          -//            (CFT, CST)
  2473.          Accept  C++ comments '//...' in C source  code. This option can
  2474.          be used to ensure compatibility with C compilers which can also
  2475.          recognize C++ comments within C source code (like Microsoft and
  2476.          Borland).
  2477.  
  2478.  
  2479.          -?             (CFT, CST, DFT, FFT, LFT)
  2480.          Shows  the command line syntax and gives  a short, but complete
  2481.          help information about the accepted commands and their syntax.
  2482.  
  2483.  
  2484.          COMMAND LINE FILES
  2485.  
  2486.          cmdfile        (CFT, CST, DFT, FFT, LFT)
  2487.          Specifies  a file with (additional)  command line options. This
  2488.          might  be useful if the command line  would be too long because
  2489.          of  the number  of options  and files  declared  or if  you are
  2490.          usually  using the same options  which can then be  stored in a
  2491.  
  2492.  
  2493.                                         40
  2494.  
  2495.  
  2496.  
  2497.          command  file. The initial '$'-character is  required to mark a
  2498.          command file.
  2499.  
  2500.          filelist            (CFT, CST, DFT, FFT, LFT)
  2501.          A file with a list of source file(s) to be processed, wildcards
  2502.          are accepted.  The list file should have every file on a single
  2503.          line.  The rules for  files containing assembler  code and path
  2504.          translation  are described above. The  initial '@'-character is
  2505.          required   to  mark  a  file  list  file.   The  '+'  sign  for
  2506.          subdirectory  processing is also possible  inside the file list
  2507.          file.
  2508.  
  2509.          [+]file             (CFT, CST, DFT, FFT, LFT)
  2510.          The  name of a source file to  be processed. More than one file
  2511.          can  be specified on  the command line.  The default assumption
  2512.          for  the  given  files is  that  they  contain  C  source code.
  2513.          Assembler  source   files  are  only  recognized  by  the  file
  2514.          extension '.ASM' (80x86 MASM/TASM) and '.S' (Intel 80960, GNU).
  2515.  
  2516.          The '+' sign indicates that, starting from the given directory,
  2517.          all subdirectories should be searched recursively for the given
  2518.          filename  search pattern.  This addition is  useful if  a large
  2519.          software project  is divided into several modules with separate
  2520.          subdirectories for  each module. In that case only the starting
  2521.          (root-)  directory with  the requested filename  search pattern
  2522.          must  be  specified to  search  the current  directory  and all
  2523.          subdirectories.
  2524.  
  2525.          If the filename or the include file specification inside a file
  2526.          contains  a relative path ('./', '.\', '../'  or '..\') it will
  2527.          be  translated into an absolute path  starting from the current
  2528.          working  directory   respectively  in  case  of  include  files
  2529.          depending  on  the  path  of  the  parent  file.  Command  line
  2530.          wildcards '*' and '?' are possible and will be accepted.
  2531.  
  2532.  
  2533.          REMARKS ON USING OPTIONS
  2534.          NONE OF  THE DESCRIBED OPTIONS IS PREDEFINED SO IT IS UP TO THE
  2535.          USER  HIMSELF TO  CUSTOMIZE HIS PREFERRED  PROCESSING BEHAVIOUR
  2536.          AND OUTPUT STYLE BY ADDING CONTROL OPTIONS NEEDED THEREFORE.
  2537.  
  2538.          This  assumption seems  to be the  best way  to give  users the
  2539.          freedom  of making their own decisions  about the features they
  2540.          really need  for doing their work, although the large number of
  2541.          options  may be confusing  for beginners.  Therefore, take some
  2542.          time  to learn about CFT and CST  and their features, read this
  2543.          manual  carefully  and  make  your  own  experience  with  this
  2544.          software.
  2545.  
  2546.          If  you start  using CFT  and CST  you  can take  the following
  2547.          command  lines  as examples  and  try other  options  to  get a
  2548.          feeling  for  what they  are  useful and  how  they  affect the
  2549.          output.
  2550.  
  2551.               CFT -m -u -M -P -T<type> -cs -Cs -n -Zs -G <file[s]>
  2552.               CST -M -P -T<type> -cs -Cs -n -Zs -G <file[s]>
  2553.  
  2554.  
  2555.  
  2556.                                         41
  2557.  
  2558.  
  2559.  
  2560.          It  is possible to declare  more than one  source file, command
  2561.          file and  list file on the command line. In that case they will
  2562.          be processed in the order they appear. Files and options can be
  2563.          placed  in  mixed  order  on  the  command  line,  there is  no
  2564.          recommended  order  for them  because all  options  (also those
  2565.          inside  command  files!) will  be processed  before  any source
  2566.          files are scanned.
  2567.  
  2568.          The  maximum command line length for DOS  is 127 characters, so
  2569.          this is  a system dependent 'natural' limit for the options and
  2570.          filenames  being declared. If  you have more  items to declare,
  2571.          place  them into command list files and  file list files, which
  2572.          do not have such limitations.
  2573.  
  2574.          Options  can also be  defined by the  environment variables CFT
  2575.          and CST like
  2576.  
  2577.               SET CFT=...
  2578.               SET CST=...
  2579.  
  2580.          To  separate single options  in the  environment string, spaces
  2581.          are  required. See also the  description for the  -D option for
  2582.          remarks on environment variable definitions.
  2583.  
  2584.          The rules for the interpretation of options is
  2585.  
  2586.          1.   if  defined, all options in  the environment variables CFT
  2587.            (for CFT) or CST (for CST) will be taken,
  2588.          2.   the  command line  options and  the  option files  will be
  2589.            interpreted in the order they appear.
  2590.  
  2591.          If an option is declared different more than once then previous
  2592.          declarations will be overwritten by the newer one.
  2593.  
  2594.          If  options  are  represented by  a  single  character  with no
  2595.          additional optional  values possible like -a or -u, they can be
  2596.          grouped  together  with  a single  leading  '-'  in  front like
  2597.          '-auM',  which  is the  same as  '-a  -u -M'.  The  last option
  2598.          however,  can have additions, for  example '-auMmWinMain' which
  2599.          can be evaluated to '-a -u -M -mWinMain'. If an option can have
  2600.          an  additional  parameter,  the  parameter  must  be  specified
  2601.          without  a  space between  the option  character.  Leaving this
  2602.          space  means that  no additional  parameter  is given  for this
  2603.          option.
  2604.  
  2605.          Filenames  being  composed  of  drive  letter, directory  name,
  2606.          filename  and file extension, in  the following referred simply
  2607.          as 'pathname',  are treated by some special procedures to force
  2608.          a unique style of their internal representation:
  2609.  
  2610.          - path names are always considered not case sensitive, so there
  2611.            is  no difference in  upper case,  lower case  and mixed case
  2612.            path  names  (the  reason  is  that  DOS  does  not make  any
  2613.            difference),
  2614.          - path names  containing './', '.\', '../' and '..\' (so called
  2615.            'relative paths')  are expanded and transformed into absolute
  2616.            paths,
  2617.  
  2618.  
  2619.                                         42
  2620.  
  2621.  
  2622.  
  2623.          - the recommended directory delimiter is '/' (UNIX-style), if a
  2624.            '\'  (DOS-style) is  recognized in  a path  name, it  will be
  2625.            replaced by '/',
  2626.          - path  names  are  always expanded  and  transformed  into the
  2627.            default style
  2628.  
  2629.               <DRIVE LETTER>:<DIRECTORY PATH>/<FILENAME>
  2630.  
  2631.            to  get a unique representation for  every filename that must
  2632.            be handled during processing,
  2633.          - filenames are operating system dependent:
  2634.               DOS: maximum length: 12 characters (8.3 format)
  2635.               WINDOWS 3.1: maximum length: 12 characters (8.3 format)
  2636.               WINDOWS NT: maximum length: 255 characters
  2637.               WINDOWS 95: maximum length: 255 characters
  2638.               OS/2: maximum length: 255 characters
  2639.  
  2640.          If  you want  to perform  database  generation (option  -G) for
  2641.          different  projects, you are  responsible to  separate them and
  2642.          avoid  overwriting  of  existing databases.  This  can  be done
  2643.          either  by giving  the databases  different  names so  that the
  2644.          database  files can  be placed  all in  the same  directory, or
  2645.          every  database must be written into its  own directory. If you
  2646.          want  to access the databases  be sure to use  the correct name
  2647.          and/or path, also within the BRIEF or MicroEMACS editors.
  2648.  
  2649.  
  2650.          COMMAND LINE EXAMPLES
  2651.  
  2652.          1.   CFT -m -u *.c
  2653.          This  program invocation  of CFT processes  all files  with the
  2654.          extension ".c" in the current directory and generates an output
  2655.          file  starting  with the  "main"-function (option  -m)  for the
  2656.          output  tree. All  functions will  be shown  in lexicographical
  2657.          order (-a), also undefined ones (-u).
  2658.  
  2659.          2.   CFT -mWinMain  -    -TMSC70,L                               aMP           -Id: -cs  -Cs -na -ve:\ -C++
  2660.          *.c ..\*.c *.cpp
  2661.          This invocation is similar to the one described above with some
  2662.          extensions. The  source files from the current (*.c, *.cpp) and
  2663.          from  the parent (..\*.c) directory,  they will be preprocessed
  2664.          (-P) with  MS-C 7.0 defines for large memory model (-TMSC70,L),
  2665.          the  include  file  path will  be  taken  from  the environment
  2666.          variable  "INCLUDE" (default for  -P) and the  path "d:" (-Id:)
  2667.          will also  be searched for. The precompiler output is stored in
  2668.          path  "e:"   (-ve:\).  C++  extensions  and  keywords  will  be
  2669.          recognized if they occur (-C++). The output will start with the
  2670.          "WinMain"-function  (-mWinMain). There  will  be a  sorted call
  2671.          statistic  (-cs) and a function summary  for every scanned file
  2672.          (-Cs).  The critical function call path  for all functions will
  2673.          be  calculated and  displayed (-na) and  the included  files of
  2674.          every source file will be shown (-M).
  2675.  
  2676.          3.   CST -S"struct _test" *.h -W2 -C++
  2677.          Start  CST  to scan  all files  in the  current  directory with
  2678.          extension  ".h" for data types.  The output should  be done for
  2679.          the  data type 'struct  _test' (-S"struct  _test"). The warning
  2680.          level is set to "2" (-W2).
  2681.  
  2682.                                         43
  2683.  
  2684.  
  2685.  
  2686.  
  2687.          4.   CFT y.c -R -Dmain=main_entry z.c -P x.c
  2688.          Start  CFT  to  produce a  reverse  calling  tree  (-R)  of the
  2689.          functions  found in  the files  "x.c", "y.c"  and "z.c"  in the
  2690.          current  directory. The files will  be preprocessed (-P) before
  2691.          file  scan, the  name "main" will  be replaced  by "main_entry"
  2692.          during preprocessing (-Dmain=main_entry).
  2693.  
  2694.          5.   CST $cst1.cmd $cst2.cmd -ve:\tmp @cstfiles +*.h -olist.v1a
  2695.          This  invocation of CST  receives its options  from the command
  2696.          files  "cst1.cmd" and  "cst2.cmd"  and stores  the preprocessor
  2697.          output  in path "e:\tmp" (-ve:\tmp).  The files being processed
  2698.          are  defined  in the  source list  file "cstfiles"  and  on the
  2699.          command line  by "+*.h". The "+*.h" file specification searches
  2700.          the current directory and all subdirectories for files with the
  2701.          extension  ".h".  The  output  file  will  be named  "list.v1a"
  2702.          (-olist.v1a).
  2703.  
  2704.          6.   CFT -a -PGNUINC -TGNUC222 -M c:\gnu\src\*.c c:\gnu\src\*.s
  2705.          -d10
  2706.          CFT  scans  all  files with  extension  ".c"  and  ".s"  in the
  2707.          directory  "c:\gnu\src".  They  will  be  preprocessed with  an
  2708.          include  file  path defined  in  environment  variable "GNUINC"
  2709.          (-PGNUINC) for  compiler type "GNUC222" (-TGNUC222). The output
  2710.          contains  all functions (-a) and  a list of  all included files
  2711.          for  every source file (-M). The output  tree will be truncated
  2712.          if the nesting level is higher than 10 (-d10).
  2713.  
  2714.          7.   CST *.c
  2715.          CST  processes all  files with  extension  ".c" in  the current
  2716.          working directory.  There are no options specified, so only the
  2717.          options set by the environment variable 'CST', if present, will
  2718.          be  used to customize the program execution.  As an example the
  2719.          command  line  options used  in example  6. can  be  defined as
  2720.          environment  variable  CST  by  'SET  CST=-aMKPGNUINC -TGNUC222
  2721.          -d10'.
  2722.  
  2723.          8.   CFT -a -PI960INC -TI960,KB *.c *.s
  2724.          CFT scans all files with extension ".c" and ".s" in the current
  2725.          directory. They  will be preprocessed with an include file path
  2726.          defined  in  environment  variable  "I960INC"  (-PI960INC)  for
  2727.          compiler type "I960", 'KB' architecture (-TI960,KB). The output
  2728.          contains all functions (-a).
  2729.  
  2730.          9.   CFT -R -M -gproj40 -Gproj41
  2731.          CFT  reads the  database named  'proj40'  (-g) and  produces as
  2732.          output the  reverse function call tree (-R), the (include) file
  2733.          interdependencies (-M) and a new database named 'proj41'.
  2734.  
  2735.          10.  CST -g -Gnew -N
  2736.          CST  reads the  default database  (-g)  and produces  as output
  2737.          another  database named 'new' (-Gnew). No  other output file is
  2738.          generated (-N).
  2739.  
  2740.  
  2741.  
  2742.  
  2743.  
  2744.  
  2745.                                         44
  2746.  
  2747.  
  2748.  
  2749.          11.  CST -N -OTEST -O+ test.h
  2750.          CST reads the file "test.h", generates no output file (-N), but
  2751.          a  byte offset calculation  file for data  type 'TEST' (-OTEST)
  2752.          and its enclosed type members (-O+).
  2753.  
  2754.  
  2755.          8   MISCELLANEOUS
  2756.  
  2757.          8.1 OUTPUT DESCRIPTION
  2758.  
  2759.          This section  gives an overview about the files being generated
  2760.          by CFT and CST and the interpretation of the results. Different
  2761.          files are produced as output depending on the options being set
  2762.          by  the user. Usually,  if -N is  not set,  all information are
  2763.          written to the default output file CFT.LST or CST.LST or to the
  2764.          file  specified by  the -o  option.  The internal  structure of
  2765.          these files and their meanings are described below. If database
  2766.          generation  is  enabled  with  option  -G,  several  files  are
  2767.          produced. They  all have a common database name to identify the
  2768.          files  that  are related  with  a project.  The  file extension
  2769.          '.DBF' marks the dBASE compatible database files, the file with
  2770.          the extension  '.CMD' contains the command line options and the
  2771.          file  with the extension '.SRC' contains  all source files that
  2772.          were   processed.  For   further   information  refer   to  the
  2773.          corresponding section in the syntax description.
  2774.  
  2775.  
  2776.          8.1.1 CFT OUTPUT
  2777.  
  2778.          The  output file is divided into several  sections. Some of the
  2779.          sections  listed  are  generated  by  default  (-), others  are
  2780.          optional  (o)  and only  displayed  if they  are  enabled  by a
  2781.          command  line   option.  Also,  the  default  sections  can  be
  2782.          customized   to  produce  the  desired   output.  The  sections
  2783.          generated for CFT are (in the order they appear):
  2784.  
  2785.          - file header
  2786.          - function  call tree/called-by hierarchy listing  (-R, -a, -m,
  2787.            -f, -dn, -V, -l)
  2788.          - function summary
  2789.          - multiple  defined  functions  and  their  location  (only  if
  2790.            detected)
  2791.          - overloaded functions and their location (only if detected)
  2792.          o undefined functions (-u)
  2793.          o function call statistics (-c[s])
  2794.          o function caller/member relations (-Z[s])
  2795.          o function call cross reference table (-z)
  2796.          o critical function call path (-n[a])
  2797.          o source file - include file dependency (-M)
  2798.          o function tables for source files (-C[s])
  2799.          - file information summary
  2800.  
  2801.          Each function is displayed like:
  2802.  
  2803.               int test() (1) <DMPCA> <TEST.C, 100>
  2804.  
  2805.          with the following meanings
  2806.  
  2807.  
  2808.                                         45
  2809.  
  2810.  
  2811.  
  2812.               - int : function return type
  2813.               - test() : function name
  2814.               - (1) : function reference number
  2815.               - <DMPCA> : found as (one or more of)
  2816.                    D = definition,
  2817.                    M = macro,
  2818.                    P = prototype,
  2819.                    C = function call,
  2820.                    A = assembler function
  2821.               - <TEST.C, 100>: filename, line number
  2822.  
  2823.          The line number is the line where the function definition block
  2824.          starts with its initial '{' and not the line where the function
  2825.          name resides. I think that this is the best solution because it
  2826.          is the point where we go really inside the function block. This
  2827.          convention  is also used by source  level debuggers which point
  2828.          on the line with the opening brace on function entry.
  2829.  
  2830.  
  2831.          8.1.2 CST OUTPUT
  2832.  
  2833.          The  output file is divided into several  sections. Some of the
  2834.          sections  listed  are  generated  by  default  (-), others  are
  2835.          optional  (o)  and only  displayed  if they  are  enabled  by a
  2836.          command  line   option.  Also,  the  default  sections  can  be
  2837.          customized   to  produce  the  desired   output.  The  sections
  2838.          generated for CST are (in the order they appear):
  2839.  
  2840.          - file header
  2841.          - data structure call tree/called-by hierarchy listing (-R, -a,
  2842.            -m, -f, -dn)
  2843.          - data type summary
  2844.          - multiple  defined  data  types and  their  location  (only if
  2845.            detected)
  2846.          o data type call statistics (-c[s])
  2847.          o data type caller/member relations (-Z[s])
  2848.          o data type call cross reference table (-z)
  2849.          o maximum data type nesting (-n[a])
  2850.          o source file - include file dependency (-M)
  2851.          o data type tables for source files (-C[s])
  2852.          - file information summary
  2853.  
  2854.          Each data type is displayed like:
  2855.  
  2856.               struct _test (1) <BSUCE> <TEST.C, 90> <TEST.C, 60>
  2857.  
  2858.          with the following meanings
  2859.  
  2860.            - struct _test : type specifier
  2861.            - (1) : reference number
  2862.            - <BSUCE> : data type (one/none of):
  2863.               B = basic type (void, char, int, ...),
  2864.               S = struct,
  2865.               U = union,
  2866.               C = class,
  2867.               E = enum
  2868.            -  <TEST.C, 90>  : filename, line  number of  type definition
  2869.            (only printed if necessary)
  2870.  
  2871.                                         46
  2872.  
  2873.  
  2874.  
  2875.            -  <TEST.C,  60>  :  filename,  line  number  of  basic  type
  2876.            definition
  2877.  
  2878.          The two  locations for the data type can occur if the data type
  2879.          is  first  defined  and  later  assigned  via  'typedef' or  by
  2880.          '#define' (if -P is not set) to another data type name:
  2881.  
  2882.          test.c: ...
  2883.          line 60: struct xyz {...};
  2884.               ...
  2885.          line 90: typedef struct xyz struct _test;
  2886.               ...
  2887.  
  2888.          Their definition is on different lines but both data type names
  2889.          refer to the same data structure.
  2890.  
  2891.          Like the  convention used for functions, the line number is the
  2892.          line  where  the structure,  union, enumeration  or  class type
  2893.          definition  block starts with its initial '{'  and not the line
  2894.          where the type name resides.
  2895.  
  2896.  
  2897.          8.1.3 OUTPUT INTERPRETATION
  2898.  
  2899.          Besides  the hierarchical structure  chart of  the function and
  2900.          data type  relationships, the resulting output contains several
  2901.          useful  information about  the program  which  can be  used for
  2902.          optimization,  reuse or  maintenance purposes.  Identifying the
  2903.          most  frequently  called  functions  is  a  good  way  to  find
  2904.          candidates  for further optimization.  Low-level functions with
  2905.          many  callers but no  called subfunctions are  ideal for reuse.
  2906.          Functions  with no callers may  be obsolete if  the function is
  2907.          also  not called  via function pointers,  and can  be discarded
  2908.          therefore. The  chance to find errors in complex functions with
  2909.          many  lines of source code, many called  functions and a lot of
  2910.          control statements is much bigger than in simple functions.
  2911.  
  2912.  
  2913.          8.2 TOOLS FOR DATABASE PROCESSING
  2914.  
  2915.          To  access  information  stored in  a  database,  the following
  2916.          utilities are available for the SXT programs:
  2917.  
  2918.               CFTN      C Function Tree Navigator
  2919.               CSTN      C Structure Tree Navigator
  2920.               DFTN      DBASE Function Tree Navigator
  2921.               FFTN      FORTRAN Function Tree Navigator
  2922.               LFTN      LISP Function Tree Navigator
  2923.  
  2924.          They  can be used to  recall the filename and  line number of a
  2925.          specific item (function or data type) from the database. If the
  2926.          requested  item is found in the database,  it will be displayed
  2927.          with its  location where it is defined or where it is found for
  2928.          the  first  time  if  there  was  no  definition  found  during
  2929.          processing.
  2930.  
  2931.          As  an  additional feature  editors like  BRIEF  3.0/3.1, QEDIT
  2932.          2.1/3.0  or MicroEMACS  3.11 can be  invoked directly  with the
  2933.  
  2934.                                         47
  2935.  
  2936.  
  2937.  
  2938.          information  to open the target file and  to move the cursor to
  2939.          the  line where the searched  item is located.  For BRIEF there
  2940.          are  several macros available  to perform  searching inside the
  2941.          editor. A  new edit window with the file at the location of the
  2942.          requested  item will  be opened if  the search  was successful.
  2943.          Also  both MicroEMACS editor  versions for DOS  and WINDOWS are
  2944.          supported.  Some of these actions are  also possible for QEDIT,
  2945.          with   slight  limitations   due   to  the   macro  programming
  2946.          capabilities.
  2947.  
  2948.          Other  user programmable editors  which should be  able to work
  2949.          with  CFTN and CSTN are  e.g. CRISP and  Codewright (both BRIEF
  2950.          compatible),  EPSILON,  ME, KEDIT,  Multi-Edit,  JED, GNU-EMACS
  2951.          ports  like  DEMACS  or  OEMACS,  the  Microsoft  editor  M  or
  2952.          integrated   development  environments  like   Borland  IDE  or
  2953.          Microsoft  PWB (this list may not be  complete). You can try to
  2954.          integrate CFTN  and CSTN into these systems by using the BRIEF,
  2955.          QEDIT  or  MicroEMACS  macro files  as  examples  for  your own
  2956.          integration development.
  2957.  
  2958.          The  version numbers for  the editors mentioned  in this manual
  2959.          indicate  those versions  for which the  described capabilities
  2960.          have been tested.
  2961.  
  2962.  
  2963.          PRECOMPILED SOURCE FILES
  2964.  
  2965.          Sometimes, if the precompiler option -P was used to process the
  2966.          C/C++  source files related  with the database,  the results of
  2967.          searches seem  to be wrong. This can happen if an identifier in
  2968.          the  source code  is in fact  defined as  a macro  and has been
  2969.          exchanged  during preprocessing  so  that the  resulting source
  2970.          processed by the analyzer is different from the original source
  2971.          and the cursor will point to an obviously wrong location or the
  2972.          search  will fail. An identifier which is  in fact a macro name
  2973.          is  unknown and not  accessible after precompiling.  It is also
  2974.          possible  that a  function being  used  in the  original source
  2975.          could  not be  found in the  database. The  reason is  that the
  2976.          function  is in fact a  'function like' macro  and was replaced
  2977.          during  preprocessing. If  different  named macros  are defined
  2978.          equal, a  search for an item may point to another location than
  2979.          the  requested. If the -P option is  not set, the same item can
  2980.          have  several  'alias'- names  due  to macro  defining.  If the
  2981.          source  code contains explicit  #line numbers,  searching for a
  2982.          specific line  may also fail. Keep these exceptions in mind for
  2983.          a correct interpretation the results when using the database.
  2984.  
  2985.  
  2986.          IMPORTANT NOTICE
  2987.  
  2988.          Recalling  information from  the database may  not be  valid if
  2989.          files  being  processed  were  edited  and  changed  after  the
  2990.          database generation  has been performed. Errors can result like
  2991.          pointing to  wrong files and/or lines if source lines have been
  2992.          deleted  or inserted, failed searches if  names have changed or
  2993.          failed accesses  to files which may have been renamed, moved or
  2994.          deleted.  To avoid  these errors, a  consistency check  for the
  2995.          file creation  date/time and file size will be performed by the
  2996.  
  2997.                                         48
  2998.  
  2999.  
  3000.  
  3001.          recall  programs. If  inconsistencies are recognized,  the user
  3002.          will be informed that the database is not up-to-date and should
  3003.          be updated by processing the source files again.
  3004.  
  3005.  
  3006.          NOTICE  TO   DEVELOPERS  USING  THE  DATABASE  FROM  THEIR  OWN
  3007.          PROGRAMS:
  3008.          There  is absolutely  no guarantee  that the  internal database
  3009.          structure   will  remain   unchanged.  The   internal  database
  3010.          structure may change without notice if this is necessary.
  3011.  
  3012.  
  3013.          COMMAND LINE SYNTAX DESCRIPTION
  3014.  
  3015.          SYNTAX:   CFTN [options] pattern
  3016.                    CSTN [options] pattern
  3017.                    DFTN [options] pattern
  3018.                    FFTN [options] pattern
  3019.                    LFTN [options] pattern
  3020.  
  3021.          OPTIONS
  3022.  
  3023.          -Eeditor
  3024.          Specifies the editor command line for option -e, overwrites the
  3025.          default  and  the  environment values.  See  the  section about
  3026.          environment   variables  for  further   information  about  the
  3027.          required format.
  3028.  
  3029.          -F
  3030.          Print  all filenames which are related  with the database. This
  3031.          option is  useful to get a complete overview about all files of
  3032.          the project.
  3033.  
  3034.          -a
  3035.          Print  all function/data type names. Useful  to generate a list
  3036.          of items, for example as input to other programs.
  3037.  
  3038.          -B
  3039.          Same  as  -a,  but prints  additionally  the  internal database
  3040.          record number. Used by BRIEF macros.
  3041.  
  3042.          -bform
  3043.          Run  search in  batch-mode, this means  that, if  the requested
  3044.          item was found, the location will be displayed on a single line
  3045.          as  "file name  line number"  (DEFAULT STYLE),  otherwise there
  3046.          will be  no output that the search failed. The output style can
  3047.          be changed by specifying 'form' to overwrite the default style.
  3048.          Like  for option -E you  can specify the  exact locations where
  3049.          the  filename and line number should be  inserted by defining a
  3050.          format  string  with %s  and  %d (See  also  the  section about
  3051.          environment  variables). For example, the  format to generate a
  3052.          command line for invoking BRIEF, QEDIT or MicroEMACS would look
  3053.          like
  3054.  
  3055.               cstn -b"b -m\"goto_line %d\" %s" ... (BRIEF)
  3056.               cstn -b"q %s -n%d" ... (QEDIT)
  3057.               cstn -b"me -G%d %s" (MicroEMACS)
  3058.  
  3059.  
  3060.                                         49
  3061.  
  3062.  
  3063.  
  3064.          This  option gives  you a  great  flexibility in  generating an
  3065.          output for your own purposes, for example to write a batch file
  3066.          or for further use in other programs.
  3067.  
  3068.          -e
  3069.          If  the requested item is  found, an editor will  be invoked to
  3070.          display the file containing the requested item. There are three
  3071.          different ways to specify the editor command line (evaluated in
  3072.          that order):
  3073.  
  3074.          1)   use option -E,
  3075.          2)   define  the  environment variables  CFTNEDIT,  CSTNEDIT or
  3076.            CXTNEDIT,
  3077.          3)   if nothing  is specified, BRIEF as  the default editor (if
  3078.            present) will be invoked with the filename and line number of
  3079.            the item  to move the cursor to its location. Ensure that the
  3080.            PATH  environment variable  is  set correctly,  including the
  3081.            path for the BRIEF directory.
  3082.  
  3083.          -fname
  3084.          Use 'name' as base name (path and filename) for database files.
  3085.          It  is also  possible to  use environment  variables (CFTNBASE,
  3086.          CSTNBASE,  CXTNBASE) for the definition  of the database names.
  3087.          If  -f and environment  variables are  not set,  a DEFAULT NAME
  3088.          will  be  used (see  also option  -G  from CFT  and  CST syntax
  3089.          description).  This allows the use  of different databases, for
  3090.          example, generated for different projects. See also the section
  3091.          about environment variables for further information.
  3092.  
  3093.          -r#
  3094.          This  option  prints  the location  for  a  selected  item with
  3095.          matching pattern  and record number #. This option requires -b.
  3096.          Used by BRIEF macros.
  3097.  
  3098.          -Ritem
  3099.          Print a cross reference list of every occurrence of 'item' with
  3100.          complete filename and line number.
  3101.  
  3102.          -Dfile
  3103.          Print a list with the contents of 'file'.
  3104.  
  3105.          -o[name]
  3106.          Print  output  to  file 'name'.  If  'name'  is  not specified,
  3107.          DEFAULT NAMES are used: CFTN.OUT resp. CSTN.OUT.
  3108.  
  3109.          pattern
  3110.          The  item to search for  in the database. This  can either be a
  3111.          function  name (CFTN)  or a  data type  name (CSTN).  There are
  3112.          three  different ways of  searching depending  how 'pattern' is
  3113.          given:
  3114.  
  3115.                 pattern exact search,
  3116.                 pattern*     the beginning  of the item  must match with
  3117.                 pattern
  3118.                 *pattern     a substring must match with pattern
  3119.  
  3120.          If  the  item to  search for  consists  of more  than  one word
  3121.          (contains  spaces), the  search pattern  must be  'quoted' like
  3122.  
  3123.                                         50
  3124.  
  3125.  
  3126.  
  3127.          "struct  _iobuf" to ensure that these  words are interpreted as
  3128.          single pattern.
  3129.  
  3130.  
  3131.          RETURN VALUES
  3132.  
  3133.          The following values are returned to DOS or the calling program
  3134.          to report the result of the database search:
  3135.  
  3136.          - 100 searched item not found,
  3137.          - 101 searched item found,
  3138.          - 102  searched item found, but  the source file  may have been
  3139.            changed (creation  date and/or file size are not equal) since
  3140.            the creation of the database (database is not up-to-date).
  3141.  
  3142.          The returned  value can be used to decide what action should be
  3143.          done for different results, for example, if the database is not
  3144.          up-to-date.
  3145.  
  3146.  
  3147.          ENVIRONMENT VARIABLES
  3148.  
  3149.          CFTNEDIT, CSTNEDIT, CXTNEDIT:
  3150.          The  editor to invoke can be defined  either by option -e or by
  3151.          defining   the  environment  variables   CFTNEDIT  (for  CFTN),
  3152.          CSTNEDIT (for CSTN) or the commonly used variable CXTNEDIT (for
  3153.          both  CFTN and CSTN)  with the format  string of  the editor of
  3154.          your choice. The format string can be used to specify the place
  3155.          where  the filename and the  line number should  be inserted to
  3156.          give  additional  information to  the  editor. Use  %s  for the
  3157.          filename  and   %d  for  the  line  number.  For  example,  the
  3158.          invocation of the default editor BRIEF could be defined like
  3159.  
  3160.               SET CFTNEDIT=b -m"goto_line %d" %s
  3161.               SET CSTNEDIT=b -m"goto_line %d" %s
  3162.               SET CXTNEDIT=b -m"goto_line %d" %s
  3163.  
  3164.          where  'b' is the BRIEF editor, '-m'  specifies the macro being
  3165.          invoked when BRIEF starts, the macro name 'goto_line' with '%d'
  3166.          as  the place to insert  the line number and  '%s' as the place
  3167.          for the  filename. Note that this example cannot be used on the
  3168.          command  line  with -E  option  because of  the  quotes.  It is
  3169.          possible to  change the order of %d and %s if another editor is
  3170.          used.
  3171.  
  3172.          Here  are additional  configuration examples for  other popular
  3173.          editors (examples are given for CFTN, similar for CSTN):
  3174.  
  3175.          EDIT (MS-DOS 5.0):  SET CFTNEDIT=edit %s or -E"edit %s" or
  3176.                           SET CFTNEDIT=edit or -Eedit
  3177.  
  3178.          VDE 1.62:        SET CFTNEDIT=vde %s or -E"vde %s" or
  3179.                           SET CFTNEDIT=vde or -Evde
  3180.  
  3181.          QEDIT 2.1/3.0:   SET CFTNEDIT=q %s -n%d or -E"q %s -n%d"
  3182.  
  3183.          MicroEMACS 3.11: SET CFTNEDIT=me -G%d %s or -E"me -G%d %s"
  3184.  
  3185.  
  3186.                                         51
  3187.  
  3188.  
  3189.  
  3190.          The  described notation allows  the user to  customize CFTN and
  3191.          CSTN  with  his  preferred  editor  and  to perform  additional
  3192.          actions  during  invocation.  If  your  editor  supports  macro
  3193.          programming like BRIEF you are free to write your own macros to
  3194.          do similar things like the CXT.CM macro given for BRIEF 3.0/3.1
  3195.          does.  I think  this is  the most  flexible  way to  give users
  3196.          control  about this option and to help  them working with their
  3197.          preferred programming environment and development tools.
  3198.  
  3199.          CFTNBASE, CSTNBASE, CXTNBASE:
  3200.          These environment  variables can be used to specify the name of
  3201.          the  database.  Similar to  the  editor  environment variables,
  3202.          CFTNBASE and CSTNBASE are related to CFTN and CSTN and CXTNBASE
  3203.          is used  for both. For example, to specify the database 'proj1'
  3204.          located in directory 'd:\develop\projects' type
  3205.  
  3206.               SET CFTNBASE=d:\develop\projects\proj1
  3207.               SET CSTNBASE=d:\develop\projects\proj1
  3208.  
  3209.          for a separate definition or
  3210.  
  3211.               SET CXTNBASE=d:\develop\projects\proj1
  3212.  
  3213.          for a common definition of the database name.
  3214.  
  3215.  
  3216.          COMMAND LINE EXAMPLES
  3217.  
  3218.          1)   CFTN *
  3219.          Displays  all  functions in  lexicographical  order  with their
  3220.          return  types,  filenames  and  line  numbers.  Gives  a  short
  3221.          overview about all functions being found.
  3222.  
  3223.          2)   CSTN -e *
  3224.          Edit all data types in lexicographical order, use default or by
  3225.          environment variable CSTNEDIT or CXTNEDIT defined editor.
  3226.  
  3227.          3)   CFTN -fproject1 -Evde -e main
  3228.          Search  database named 'project1' for  function 'main' and edit
  3229.          with editor 'vde'.
  3230.  
  3231.          4)   CSTN -b "union REGS"
  3232.          Search  for data type 'union  REGS' and display,  if found, the
  3233.          filename and line number
  3234.  
  3235.          5)   CSTN -e -E"q %s -n%d" -fcft tmbuf
  3236.          Search  database 'cft'  for data  type  'tmbuf' and  invoke, if
  3237.          found,  the editor  'q' (QEDIT 2.1/3.0)  with the  filename and
  3238.          line number
  3239.  
  3240.  
  3241.          SEARCHING INSIDE BRIEF (Version 3.0)
  3242.  
  3243.          This  feature is one of the most  powerful enhancements for the
  3244.          BRIEF editor and offers the user full control over the complete
  3245.          source code of software projects no matter how big they are and
  3246.          how  many files they include. It extends  the BRIEF editor to a
  3247.          comfortable  hypertext source code browser  and locator system.
  3248.  
  3249.                                         52
  3250.  
  3251.  
  3252.  
  3253.          The browser  allows its user to find and read various important
  3254.          program  constructs like  functions and  data types  in several
  3255.          files  simultaneously  and moving  between  them.  The complete
  3256.          project with  several source and include files appears as if it
  3257.          were a  'whole-part'. The browser helps the programmer to learn
  3258.          about  the  existing  program structures  and  supports  him in
  3259.          developing  new and  maintaining existing code.  The programmer
  3260.          can  use the generated output files CFT.LST  or CST.LST (or the
  3261.          one he  created with the -o option) to walk along the hierarchy
  3262.          tree  chart and to select from there  the function or data type
  3263.          that should be displayed in detail.
  3264.  
  3265.          The following features are implemented as macros:
  3266.  
  3267.          - searching for a specific item, tagged or marked
  3268.          - building menus of all defined items
  3269.          - building menus of all references to a specific item
  3270.          - building menus of all processed files
  3271.          - building menus of all items defined in the current file
  3272.          - searching for a specific item cross reference number
  3273.          - changing the database name
  3274.  
  3275.          Every  function  and data  type  can be  accessed  with  just a
  3276.          keystroke by  moving the cursor on it ("tagging") and executing
  3277.          a macro  to locate the item and zoom  into the file where it is
  3278.          defined. The user does no longer have to remember the filenames
  3279.          and  locations where the  functions and data  types are defined
  3280.          nor does he have to change the files, directories and drives to
  3281.          access the files manually.
  3282.  
  3283.          It  is  possible to  build  interactive dialog  menus  with all
  3284.          functions or  data types in lexicographical order and to select
  3285.          an item to display. This is very useful to get a quick overview
  3286.          about  all accessible  functions and  data  types of  the whole
  3287.          project.  It is  also possible to  build an  interactive dialog
  3288.          menu  with  all filenames  in lexicographical  order  which are
  3289.          stored in the database and to select one file to open for edit.
  3290.          Other  menus are  available for  file  contents lists  and item
  3291.          cross references.  All information to perform these actions are
  3292.          stored  in  the  databases generated  by  processing  the files
  3293.          related with the project.
  3294.  
  3295.          To  invoke CFTN and  CSTN inside  BRIEF, the  macro file CXT.CM
  3296.          must be  loaded (with <F9> CXT.CM), which makes the implemented
  3297.          macros available. These macros are
  3298.  
  3299.               MACRO NAME KEY ASSIGNMENT (defined in CXTKEYS.CM)
  3300.  
  3301.               cft            Shift F1
  3302.               cftmenu        Shift F2
  3303.               cftxrefmenu         Shift F3
  3304.               cftxrefmenuagain    Shift F4
  3305.               cftdefmenu          Shift F7
  3306.               cftfilemenu         Shift F8
  3307.               cftfind             Shift F11
  3308.               cftbase        Shift F12
  3309.  
  3310.  
  3311.  
  3312.                                         53
  3313.  
  3314.  
  3315.  
  3316.               cst            Ctrl F1
  3317.               cstmenu        Ctrl F2
  3318.               cstxrefmenu         Ctrl F3
  3319.               cstxrefmenuagain    Ctrl F4
  3320.               cstdefmenu          Ctrl F7
  3321.               cstfilemenu         Ctrl F8
  3322.               cstfind             Ctrl F11
  3323.               cstbase        Ctrl F12
  3324.  
  3325.               cxtbase        Alt Tab
  3326.               cxtsearchxref  Ctrl Tab
  3327.               cxthelp        <unassigned>
  3328.  
  3329.          This  macro key assignment list is  also available within BRIEF
  3330.          as  a help screen which can be  invoked by the macro 'cxthelp'.
  3331.          The  CXT help information is not part  of the BRIEF help system
  3332.          because  this would  need modifications  of the  original BRIEF
  3333.          help files.
  3334.  
  3335.          Instead  of loading the file CXT.CM and  typing the macro names
  3336.          manually, you can load the macro file CXTKEYS.CM which performs
  3337.          automatic loading of the CXT.CM file if any of the above listed
  3338.          macros is invoked with a hot-key. To simplify working with this
  3339.          package,   the  CXTKEYS.CM   macro   file  also   contains  key
  3340.          assignments  for the macros. These hot-keys  offer a "point and
  3341.          shoot" hypertext like feeling. The macro source file CXTKEYS.CB
  3342.          contains the source code for CXTKEYS.CM so that you are able to
  3343.          make  changes like the key assignments  for your personal needs
  3344.          or  to move the  initialization function to  the BRIEF start-up
  3345.          macro file  (For further information about BRIEF macros see the
  3346.          BRIEF  manuals). To load these  macros and to  execute CFTN and
  3347.          CSTN,  which are invoked from inside BRIEF,  be sure to set the
  3348.          directory path  correctly. It is also necessary to allow access
  3349.          to  the macro file  DIALOG.CM which contains  the functions for
  3350.          dialog menu building and processing.
  3351.  
  3352.          A search can be started by simply moving the cursor on the item
  3353.          to search for or by marking a block with the item (necessary if
  3354.          search  pattern contains more than one  word like 'struct xyz')
  3355.          and  then running one  of the  following macros  (or press hot-
  3356.          keys):
  3357.  
  3358.               <F10> cft (function search)
  3359.               <F10> cst (data type search)
  3360.  
  3361.          It is also  possible to type the name of the item to search for
  3362.          manually. To do this you must run one of the following macros:
  3363.  
  3364.               <F10> cftfind <item> (function search)
  3365.               <F10> cstfind <item> (data type search)
  3366.  
  3367.          If  the  search was  successful,  a new  window  with  the file
  3368.          containing  the  item will  be opened  and the  cursor  will be
  3369.          placed   at   the  line   where   the  item   is   located.  If
  3370.          inconsistencies have  been detected, the user will be informed.
  3371.          If the requested item or the source file containing the item is
  3372.          not found, a message will be given. The macros for building the
  3373.          function and data type dialog menu are
  3374.  
  3375.                                         54
  3376.  
  3377.  
  3378.  
  3379.  
  3380.               <F10> cftmenu (function menu)
  3381.               <F10> cstmenu (data type menu)
  3382.  
  3383.          You  can scroll through  the entries  and select  an item which
  3384.          should be displayed. To access databases other than the default
  3385.          ones, there are two ways to change the base names:
  3386.  
  3387.          1)   Set  the   environment  variables  CFTNBASE,  CSTNBASE  or
  3388.            CXTNBASE  (see description above). By  loading the macro file
  3389.            CXT.CM these variables will be used for initialization.
  3390.  
  3391.          2)   To  change the  base names  from  inside BRIEF,  there are
  3392.            three  macros to do  this. They overwrite  the initial values
  3393.            given by the environment variables:
  3394.  
  3395.               <F10> cftbase change base name for function search
  3396.               <F10> cstbase change base name for data type search
  3397.               <F10> cxtbase change both CFT and CST base name
  3398.  
  3399.          With  these features it is  possible to set  default values for
  3400.          the  database files  or to  change between  different databases
  3401.          without  leaving  BRIEF  which  gives  the  user  a maximum  of
  3402.          flexibility. You  can display a menu list with all source files
  3403.          being scanned for the database by typing
  3404.  
  3405.               <F10> cftfilemenu (CFT file menu)
  3406.               <F10> cstfilemenu (CST file menu)
  3407.  
  3408.          With this  feature you can get a quick overview about all files
  3409.          related  with the database.  Other menu  driven options concern
  3410.          the displaying  of all cross references to a specific item (see
  3411.          macro 'cst' for information about marking) with the macros
  3412.  
  3413.               <F10> cftxrefmenu (CFT cross reference menu)
  3414.               <F10> cftxrefmenuagain (show previous menu again)
  3415.               <F10> cstxrefmenu (CST cross reference menu)
  3416.               <F10> cstxrefmenuagain (show previous menu again)
  3417.  
  3418.          and  the  displaying of  a file  contents list  for  the actual
  3419.          source file with the macros
  3420.  
  3421.               <F10> cftdefmenu (CFT file menu)
  3422.               <F10> cstdefmenu (CST file menu)
  3423.  
  3424.          To  search  for  the  first  appearance  of  a  specific  cross
  3425.          reference  number like '(123)' in  a CFT or  CST output listing
  3426.          file, move the cursor to the reference number and type
  3427.  
  3428.               <F10> cxtsearchxref (search cross reference)
  3429.  
  3430.          The  macro extracts  the complete number  and searches  for its
  3431.          first  occurrence by starting from the  beginning of the output
  3432.          file.  With this macro you can move  quickly from any reference
  3433.          to its initial description.
  3434.  
  3435.          All  the above  described macro  functions  are defined  in the
  3436.          BRIEF macro file CXT.CB. These macros make extensive use of the
  3437.  
  3438.                                         55
  3439.  
  3440.  
  3441.  
  3442.          several options of CFTN resp. CSTN, which are described earlier
  3443.          in detail.
  3444.  
  3445.  
  3446.          SEARCHING INSIDE QEDIT (2.1 and 3.0)
  3447.  
  3448.          The  popular shareware editor QEDIT  with its macro programming
  3449.          capabilities  allows, like the  BRIEF editor,  the searching of
  3450.          functions and  data types from inside the editor. The following
  3451.          examples  for QEDIT macros  act, with  slight limitations, like
  3452.          the BRIEF macros 'cft' and 'cst':
  3453.  
  3454.          CFT function searching, assigned to <SHIFT F9>:
  3455.  
  3456.            #f9  MacroBegin MarkWord  Copy Dos  'cftn  -b '  Paste '>tmp'
  3457.            Return Return  EditFile 'tmp' Return AltWordSet MarkWord Copy
  3458.            DefaultWordSet  EditFile Paste  Return EditFile  'tmp' Return
  3459.            EndLine CursorLeft MarkWord Copy Quit NextFile GotoLine Paste
  3460.            Return
  3461.  
  3462.          CST data type searching, assigned to <SHIFT F10>:
  3463.  
  3464.            #f10  MacroBegin MarkWord  Copy Dos 'cstn  -b '  Paste '>tmp'
  3465.            Return Return  EditFile 'tmp' Return AltWordSet MarkWord Copy
  3466.            DefaultWordSet  EditFile Paste  Return EditFile  'tmp' Return
  3467.            EndLine CursorLeft MarkWord Copy Quit NextFile GotoLine Paste
  3468.            Return
  3469.  
  3470.          These   QEDIT  macro  definitions   can  be   placed  into  the
  3471.          'qconfig.dat' configuration  file and added to 'q.exe' with the
  3472.          'qconfig.exe'  configuration  utility  (For  additional details
  3473.          about QEDIT macro programming see the QEDIT documentation). The
  3474.          two  macros  perform the  following actions:  mark  the current
  3475.          word,  execute the CFTN or CSTN database  search for the marked
  3476.          word via dos and redirect the output to file 'tmp', read target
  3477.          filename from 'tmp' and open target file, read line number from
  3478.          'tmp' and go to the selected line.
  3479.  
  3480.          These  macros are  working almost  similar  to those  used from
  3481.          BRIEF,  but they have  some limitations  in their functionality
  3482.          due to  the limited capabilities of the QEDIT macro programming
  3483.          language:
  3484.  
  3485.          - there is no error check for a correct cursor location,
  3486.          - the searched item must always be a single word like 'main' or
  3487.            'size_t',  a combined pattern  like 'struct  iobuf' cannot be
  3488.            searched,
  3489.          - there  is  no error  check if  the search  was  successful or
  3490.            failed or the database is not up-to-date,
  3491.          - if the  target file is the same as that from which the search
  3492.            started and  other additional files are also open (QEDIT ring
  3493.            buffer), probably a wrong file will be accessed,
  3494.          - the name  of the database cannot be changed, the searches are
  3495.            performed  either with the default  database or those defined
  3496.            by the environment variables.
  3497.  
  3498.  
  3499.  
  3500.  
  3501.                                         56
  3502.  
  3503.  
  3504.  
  3505.          SEARCHING INSIDE MicroEMACS (Version 3.11, DOS & WINDOWS)
  3506.  
  3507.          The  latest  editor  which is  now  supported  with  macros for
  3508.          database  access is  MicroEMACS 3.11. The  macro file  is named
  3509.          CXT_ME.CMD  and should  be place  in the  MircoEMACS directory.
  3510.          This  macro file works with the DOS  and the WINDOWS version of
  3511.          MicroEMACS 3.11.
  3512.  
  3513.          The following macros are available:
  3514.  
  3515.          -    cft        function search for tagged item
  3516.          -    cst        data type search for tagged item
  3517.          -    cftmark    function search for marked item
  3518.          -    cstmark    data type search for marked item
  3519.          -    cftfind    function search for user defined item
  3520.          -    cstfind    data type search for user defined item
  3521.          -    cftfile    list of all CFT files
  3522.          -    cstfile    list of all CST files
  3523.          -    cftbase    set CFT database name
  3524.          -    cstbase    set CST database name
  3525.          -    cxtbase    set both CFT and CST database name
  3526.  
  3527.          They can be invoked by loading the macro file CXT_ME.CMD with
  3528.  
  3529.               ESC CTRL+S CXT_ME.CMD
  3530.  
  3531.          and running the macro with
  3532.  
  3533.               ESC CTRL+E <macro name>
  3534.  
  3535.          If the macros are used with the MicroEMACS WINDOWS version, you
  3536.          may  have to change the DOSEXEC.PIF file,  which is part of the
  3537.          MicroEMACS  3.11  distribution package.  During  the  CXT macro
  3538.          execution, the shell command may stop after execution and waits
  3539.          for  the  <return>  key  pressed  to  continue.  To avoid  this
  3540.          interruption,  you can enable  it by  editing the  PIF file and
  3541.          select   "Close  window   after  execution".   The  environment
  3542.          variables CFTNBASE,  CSTNBASE and CXTNBASE are used in the same
  3543.          way as in the BRIEF version. Key-assignments to macro procedure
  3544.          names  are not performed, if you prefer  hot-keys, you are free
  3545.          to do this for yourself.
  3546.  
  3547.          In the MicroEMACS WINDOWS version, however, the user accessible
  3548.          macros  can be  integrated  into the  "Miscellaneous" pull-down
  3549.          menu  (thanks to the incredible  macro programming capabilities
  3550.          of  MicroEMACS!). To  view the generated  output file  with its
  3551.          semi  graphic  frames,  change the  font  type  and  select for
  3552.          example  the  'TERMINAL'  font from  the  OEM  font  list which
  3553.          supports semi graphic characters.
  3554.  
  3555.  
  3556.          8.3 INTEGRATION INTO PROGRAM DEVELOPMENT ENVIRONMENTS
  3557.  
  3558.          Invoking CFT and CST directly from inside editors or integrated
  3559.          programming  environments (IDE) and displaying  the results can
  3560.          be  a  very  useful feature  during  program  development. With
  3561.          advanced  IDE's like that of Borland C++  or Microsoft PWB this
  3562.          is an easy task.
  3563.  
  3564.                                         57
  3565.  
  3566.  
  3567.  
  3568.  
  3569.          The Borland IDE has in its system menu a section with 'transfer
  3570.          items. It contains programs that can be invoked from inside the
  3571.          IDE  like TASM or GREP. To  add CFT and CST  as new entries you
  3572.          have to  go to the OPTIONS menu and open 'TRANSFERS...'. Choose
  3573.          a  free entry in the table and  select EDIT. A window will open
  3574.          with  3 edit lines.  In first  line called  'Program Title' you
  3575.          must  write 'C~FT' resp. 'C~ST' as the  name being displayed in
  3576.          the  transfer section.  The '~' prepends  the hot-keys  'F' and
  3577.          'S'.  In the second line  called 'Program Path'  you must write
  3578.          'CFTIDE'  resp.  'CSTIDE',  maybe with  the  complete  path, if
  3579.          necessary. 'CFTIDE'  and 'CSTIDE' are batch files which perform
  3580.          the  invocation of  CFT resp. CST  together with  the necessary
  3581.          options. These batch files are part of the CXT package, you can
  3582.          change the options defined there if you need other ones. In the
  3583.          third  line  called 'Command  Line'  you must  write  the macro
  3584.          commands '$EDNAME $NOSWAP $CAP EDIT'. These macros transfer the
  3585.          filename  in the  current edit  window  ($EDNAME) to  the batch
  3586.          file,  suppress  window  swapping  ($NOSWAP)  and  capture  the
  3587.          processing results  in an own edit window ($CAP EDIT). The last
  3588.          step  is  to  save  these  entries,  then  the  integration  is
  3589.          completed and  CFT and CST can be used as if they were built-in
  3590.          functions.  The processing results are shown  in an edit window
  3591.          which can  be scrolled, resized or moved. By adding CFT and CST
  3592.          to  the IDE it is  much easier for the  programmer to use these
  3593.          tools.
  3594.  
  3595.  
  3596.          8.4 IMPROVING EXECUTION SPEED
  3597.  
  3598.          CFT and  CST are disk storage based programs because the source
  3599.          and  include files, the  intermediate precompiler  file and the
  3600.          output  file must be read  from and written to  hard disk. This
  3601.          means that  the execution speed of CFT and CST depends at first
  3602.          on  the speed of the physical storage  medium and not (only) on
  3603.          the  speed of the  CPU. There are  several ways  to improve the
  3604.          program performance:
  3605.  
  3606.          - install a RAM-disk and
  3607.            a) start CFT and CST from there so that the intermediate file
  3608.            and the resulting output file will be stored there (but don't
  3609.            forget to copy the output file to the hard disk before power-
  3610.            off), or
  3611.            b) use  the -v option to redirect only the precompiler output
  3612.            file  (scanner input file) to the  RAM-disk from anywhere the
  3613.            program is started (the RAM-disk must be large enough to hold
  3614.            the  largest possible temporary file,  otherwise a disk-write
  3615.            error will occur),
  3616.          - use  a hard disk cache program  like SmartDrive, HyperDisk or
  3617.            PC-Cache,
  3618.          - use a faster hard disk,
  3619.          - and finally, of course, use a faster and more powerful CPU.
  3620.  
  3621.          The most  effective combination is option -v with a RAM-disk as
  3622.          destination  path and  hard disk caching  together with  a fast
  3623.          hard disk drive. If the disk cache is large enough to hold most
  3624.          of the  frequently called include files, the execution speed is
  3625.          about 2.5 to 3 times faster than without. This is a significant
  3626.  
  3627.                                         58
  3628.  
  3629.  
  3630.  
  3631.          speed-up  especially for projects with a  large number of files
  3632.          and many included files in each source file.
  3633.  
  3634.          During  program execution with preprocessing  (option -P), most
  3635.          of  the time  will be  consumed to  preprocess the  given input
  3636.          files  and  the  related  include  files  and  to generate  the
  3637.          preprocessor  output file. The scanning  for functions (CFT) or
  3638.          data  types  (CST)  takes only  a  small  amount  of  time. The
  3639.          function/data  type relations are computed  while the output is
  3640.          generated  and  written  to  disk,  there  is  no  precomputing
  3641.          necessary.
  3642.  
  3643.          The  function for  critical  call path/nesting  level detection
  3644.          depends  only on the number of functions  or structures and not
  3645.          on the  call/declaration nesting complexity. The execution time
  3646.          grows linear with the number of items (functions/structures) to
  3647.          process and is very fast!
  3648.  
  3649.          Be  aware of the fact that the  processing of a large number of
  3650.          files  can take quite a  long time (from several  minutes up to
  3651.          hours on  lower performance machines!), especially if option -P
  3652.          for preprocessing is enabled.
  3653.  
  3654.          The generation  of the output file and writing to disk can also
  3655.          take  some time if the number of  items to display is large and
  3656.          the  nesting structure is complex.  If the number  of items and
  3657.          source  files is  very large,  one of  the most  time consuming
  3658.          options  is the function/data type  file reference (option -z).
  3659.          The  writing and reading of the database  files (options -G and
  3660.          -g)  takes also some time due to  the large number of different
  3661.          information.
  3662.  
  3663.          Don't  panic if there seems  to be no disk  access for a longer
  3664.          time,  the  reason is  just that  there may  be  time consuming
  3665.          computations and that the output will be buffered internally to
  3666.          reduce  the number of disk accesses and  therefore speed up the
  3667.          output!
  3668.  
  3669.          To speed  up the SXTWIN program execution you should switch off
  3670.          the message  output and analysis progress information (filename
  3671.          and  line number) with the 'Info' menu  to avoid time consuming
  3672.          screen  updates. The program  can also be  run 'iconized', this
  3673.          also avoids screen updates.
  3674.  
  3675.          For more  detailed information about the program efficiency see
  3676.          appendix 4.
  3677.  
  3678.  
  3679.          8.5 PROBLEMS
  3680.  
  3681.          8.5.1 FREQUENTLY ASKED QUESTIONS (FAQ)
  3682.  
  3683.          ARE THERE ANY RESTRICTIONS IN THE USE OF THE ANALYSIS RESULTS?
  3684.          No restrictions  for REGISTERED users, they can use the results
  3685.          for   all   purposes  like   program   documentation,  customer
  3686.          information or debugging as long as a notice about the name and
  3687.          copyright of the used SXT program is given.
  3688.  
  3689.  
  3690.                                         59
  3691.  
  3692.  
  3693.  
  3694.          WHY  IS  NO OS/2  IPF SOURCE  CODE FOR  OS/2  INFORMATION FILES
  3695.          GENERATED?
  3696.          The OS/2 IPF functionality, comparable with the MS-Windows Help
  3697.          system,  has  limitations  which  are  not  acceptable for  SXT
  3698.          programs. According to the OS/2 3.0 online help information, it
  3699.          is  not possible to  generate a  single IPF  source file larger
  3700.          than  64K and a  single source line  cannot have  more than 255
  3701.          characters.  Both  limits  are regularly  exceeded  by  the SXT
  3702.          programs.
  3703.  
  3704.          WHY ARE SEVERAL DATABASE FILES FOR EVERY PROJECT GENERATED?
  3705.          Separating  the  analysis items  (identifier  names, filenames,
  3706.          relationships, ...) of one project into several closely related
  3707.          database  files  is the  best  way to  achieve  minimum storage
  3708.          requirements  and to optimize  disk usage. This  way of storage
  3709.          has  no redundancies compared  to storage in  a single database
  3710.          file.
  3711.  
  3712.          WHY IS THERE NO CROSS REFERENCE FOR VARIABLES INCLUDED?
  3713.          This  would  need much  additional  memory and  slows  down the
  3714.          analysis process. There would also be a lot of multiple defined
  3715.          names in  different contexts to be managed if several files are
  3716.          analyzed.  A lot of tools  exist which perform  this task quite
  3717.          good e.g.  the integrated compiler environments or other source
  3718.          code analyzers.
  3719.  
  3720.          WHY ARE CFT AND CST NOT COMBINED IN ONE PROGRAM?
  3721.          Historical  and  practical  reasons:  the  CFT development  was
  3722.          started  before CST and  both programs are  optimized for their
  3723.          own special  purposes. Combining them would complicate them and
  3724.          slow  down the analysis  process. Also  the memory requirements
  3725.          would grow.
  3726.  
  3727.          8.5.2 TROUBLE SHOOTING
  3728.  
  3729.          This  section  contains  information  about  problems  and  the
  3730.          reasons  which may occur during the use  of SXT programs. It is
  3731.          recommended  that users should read  the complete documentation
  3732.          to have  an overview about the features before they start using
  3733.          the programs and run into any unexpected troubles. See also the
  3734.          chapter   about   'PROGRAM   LIMITATIONS'   and   the  document
  3735.          'PROBLEMS.DOC'.
  3736.  
  3737.          UNEXPECTED RESULTS WHILE RUNNING THE SXT COMMAND LINE TEXT MODE
  3738.          VERSIONS UNDER WINDOWS 3.1
  3739.          The  386 versions cannot run under Windows  3.1, they are using
  3740.          the CPU  exclusive and can therefore not co-exist with Windows,
  3741.          only  the  real mode  versions  can. In  Windows  enhanced mode
  3742.          (virtual   386  mode),  the  real   mode  versions  cannot  run
  3743.          simultaneously  in several independent DOS-windows  if they are
  3744.          working  in  the  same  directory  or  use  the same  temporary
  3745.          directory,  because the  temporary intermediate files  may have
  3746.          the  same names  and will conflict  due to  multiple concurrent
  3747.          accesses. This may also happen if the same files are scanned or
  3748.          included.  The use  of SHARE.EXE is  recommended to  catch such
  3749.          file  access  conflicts, see  your DOS  manual  for information
  3750.          about the installation of SHARE.
  3751.  
  3752.  
  3753.                                         60
  3754.  
  3755.  
  3756.  
  3757.          MICROEMACS FOR WINDOWS SEEMS TO HANG DURING DATABASE ACCESS AND
  3758.          DOES NOT RETURN
  3759.          The  reason  is usually  quite simple:  The shell  call  to DOS
  3760.          through DOSEXEC.PIF waits for a keystroke to continue execution
  3761.          and  to return  to WINDOWS.  You may  change this  behaviour by
  3762.          editing  the  DOSEXEC.PIF  file  (see  MicroEMACS  section  for
  3763.          further information).
  3764.  
  3765.          A PROGRAM CANNOT BE EXECUTED
  3766.          The  program path is not specified  in the environment variable
  3767.          PATH,  the  programs are  not  yet installed  in  the specified
  3768.          directory,  attempt to start a 386 protected  mode version on a
  3769.          80286 (or lower) computer.
  3770.  
  3771.          EXECUTION STOPPED WITH MESSAGE "OUT OF MEMORY"
  3772.          An  attempt  to  allocate  memory  has  failed.  Try to  remove
  3773.          unnecessary  memory   resident  TSR  programs  and/or  use  the
  3774.          protected mode versions if you have an 80386 or higher. If this
  3775.          message  happens for the protected mode  versions, there is not
  3776.          enough  free disk space  for the  swap file.  Set the temporary
  3777.          directory,  defined  by  the  'TMP'  resp.  'TEMP'  environment
  3778.          variable, to another drive with more free disk space.
  3779.  
  3780.          WRITING THE OUTPUT FILE TAKES A LONG TIME
  3781.          A large  number of information must be handled, slow CPU and/or
  3782.          hard  disk. Use option -v  to redirect intermediate  files to a
  3783.          faster RAM-disk (if such is present).
  3784.  
  3785.          THE BRIEF MACROS CANNOT BE EXECUTED
  3786.          The macro  file is not loaded, other macros with the same names
  3787.          or assigned keys already exist.
  3788.  
  3789.          THE BRIEF OR MICROEMACS MACROS CANNOT BE LOADED
  3790.          The  path to  the macro  file location  must be  specified when
  3791.          loading  the macros, if they  are not in  the default directory
  3792.          for the editor.
  3793.  
  3794.          THE BRIEF MACROS DO NOT FIND ANY FUNCTIONS OR DATA TYPES
  3795.          There is  no access to CFTN, CSTN, DFTN (...), due to incorrect
  3796.          path  specification, no  database is present,  the path  to the
  3797.          database files is incorrect, the database name is incorrect.
  3798.  
  3799.          THE  BYTE   OFFSET  CALCULATION  FILE  "CST_OFFS.C"  CANNOT  BE
  3800.          COMPILED
  3801.          Several reasons:  Necessary data types or include files are not
  3802.          specified  or the  CST processing was  done with  include files
  3803.          other  than those being  used for  compiling. If  the number of
  3804.          data  type  information  is too  large,  some  compilers cannot
  3805.          compile  the  large  number  of  statements  in  a single  file
  3806.          generated  from CST  ('out of  heap  space', 'code  segment too
  3807.          large' or  other messages like that). In that case you may have
  3808.          to  split the  file into  several smaller  files or  reduce the
  3809.          number of data types to display.
  3810.  
  3811.          LOCATING ITEMS IN THE BRIEF EDITOR POINTS TO WRONG PLACES
  3812.          Searching  items from within  the BRIEF editor  points to wrong
  3813.          lines,  the requested  item is  not present  there or  the file
  3814.          seems to  be corrupted. This can have several reasons: The file
  3815.  
  3816.                                         61
  3817.  
  3818.  
  3819.  
  3820.          is  not  up-to-date and  has  been changed  since  the database
  3821.          generation  so that  the line references  are no  longer valid.
  3822.          Another  reason can be that the source  file has explicit #line
  3823.          numbers  as  it is  usual  for files  produced  by  source code
  3824.          generators  like YACC/BISON or LEX/FLEX. A  third reason may be
  3825.          that  the source file was  generated on an UNIX  system and has
  3826.          therefore only  LF instead of CR+LF as end-of-line delimiter so
  3827.          that BRIEF cannot display the file correctly, the file seems to
  3828.          be written  in a single line. If possible convert such files to
  3829.          DOS text format with UNIX2DOS or other utilities.
  3830.  
  3831.          THE SOURCE ANALYSIS WITH THE SXT WINDOWS VERSIONS IS VERY SLOW
  3832.          Windows  adds a lot  of overhead  to the  program execution and
  3833.          there  is no  possibility to  avoid this,  but there  are three
  3834.          things  to speed up the SXTWIN programs.  First, switch off the
  3835.          message and  progress information output ('Info' menu) to avoid
  3836.          time  consuming screen updates. Second,  if possible, specify a
  3837.          RAM-disk drive  for the temporary files (option -v). Third, run
  3838.          the program as an icon, because this avoids any screen updates.
  3839.  
  3840.  
  3841.  
  3842.  
  3843.  
  3844.  
  3845.  
  3846.  
  3847.  
  3848.  
  3849.  
  3850.  
  3851.  
  3852.  
  3853.  
  3854.  
  3855.  
  3856.  
  3857.  
  3858.  
  3859.  
  3860.  
  3861.  
  3862.  
  3863.  
  3864.  
  3865.  
  3866.  
  3867.  
  3868.  
  3869.  
  3870.  
  3871.  
  3872.  
  3873.  
  3874.  
  3875.  
  3876.  
  3877.  
  3878.  
  3879.                                         62
  3880.  
  3881.  
  3882.  
  3883.          8.6 REFERENCES
  3884.  
  3885.          Brian  W.  Kernighan,  Dennis M.  Ritchie:  "The  C Programming
  3886.          Language", Prentice Hall, Englewood Cliffs, Second Edition 1988
  3887.  
  3888.          Samuel P. Harbison, Guy L. Steele Jr.: "C: A Reference Manual",
  3889.          Prentice Hall, Englewood Cliffs, Third Edition 1991
  3890.  
  3891.          Bjarne  Stroustrup:  "The C++  Programming  Language", Addison-
  3892.          Wesley, Second Edition 1992
  3893.  
  3894.          Bjarne Stroustrup:  "The Design and Evolution of C++", Addison-
  3895.          Wesley, 1994
  3896.  
  3897.          Margaret  A.  Ellis,  Bjarne  Stroustrup:  "The  Annotated  C++
  3898.          Reference Manual" (ARM), Addison-Wesley, Second Edition 1991
  3899.  
  3900.          "Rationale  for  American  National  Standard  for  Information
  3901.          Systems  -   Programming  Language  C"  (can  be  obtained  via
  3902.          anonymous  FTP from  ftp.uu.net in '/doc/standards/ansi/X3.159-
  3903.          1989/ratinale.PS.Z')
  3904.  
  3905.          "Working  Paper for  Draft Proposed International  Standard for
  3906.          Information  Systems -  Programming  Language C++",  AT&T, ANSI
  3907.          committee X3J16, ISO working group WG21, January 28, 1993
  3908.  
  3909.          "Working  Paper for  Draft Proposed International  Standard for
  3910.          Information  Systems -  Programming  Language C++",  AT&T, ANSI
  3911.          committee X3J16, ISO working group WG21, April 28, 1995
  3912.  
  3913.          Bjarne  Stroustrup,  Keith Gorlen,  Phil  Brown,  Dennis Mancl,
  3914.          Andrew  Koenig:  "UNIX System  V  - AT&T  C++  Language System,
  3915.          Release 2.1 - Selected Readings", AT&T, 1989
  3916.  
  3917.          Goldberg, A.:  "Programmer as Reader", IEEE Software, September
  3918.          1987
  3919.  
  3920.          L.W.  Cannon, R.A.  Elliot, L.W.  Kirchhoff, J.H.  Miller, J.M.
  3921.          Milner,  R.W. Mitze, E.P. Schan,  N.O. Whittington, H. Spencer,
  3922.          D.   Keppel,  M.  Brader:  "Recommended   C  Style  and  Coding
  3923.          Standards",  Technical Report,  in the Public  Domain, Revision
  3924.          6.0, July 1991 (revised and updated version of the 'AT&T Indian
  3925.          Hill  style  guide', can  be  obtained via  anonymous  FTP from
  3926.          cs.washington.edu in '~ftp/pub/cstyle.tar.Z')
  3927.  
  3928.          A. Dolenc, A. Lemmke, D. Keppel, G.V. Reilly: "Notes on Writing
  3929.          Portable  Programs  in  C",  Technical  Report,  in the  Public
  3930.          Domain,  Revision   8,  November  1990  (can  be  obtained  via
  3931.          anonymous FTP from cs.washington.edu in '~ftp/pub/cport.tar.Z')
  3932.  
  3933.          M.  Henricson,  E.  Nyquist:  "Programming  in  C++, Rules  and
  3934.          Recommendations",  Technical  Report,  in  the  Public  Domain,
  3935.          Ellemtel Telecommunication Systems Laboratories, Alvsjo/Sweden,
  3936.          Document  No.  M 90  0118  Uen,  Rev. C  (can  be  obtained via
  3937.          anonymous   FTP   from  various   sites   as   'rules.ps.Z'  or
  3938.          'c++rules.ps.Z')
  3939.  
  3940.          H. Wehnes: "FORTRAN 77", 3. Auflage, Carl Hanser Verlag, 1984
  3941.  
  3942.                                         63
  3943.  
  3944.  
  3945.  
  3946.  
  3947.          H.  Sigl:  "dBase/Foxbase/Clipper  -  Globalreferenz",  Addison
  3948.          Wesley, 1989
  3949.  
  3950.          "A Beginner's Guide to HTML", available via World Wide Web from
  3951.          'http://www.ncsa.uiuc.edu/General/Internet/WWW/HTMLPrimer.html'
  3952.  
  3953.  
  3954.          Compiler  (on-line) reference manuals and related documentation
  3955.          (language references, language implementations and extensions):
  3956.          - Microsoft C 5.1
  3957.          - Microsoft C 6.0
  3958.          - Microsoft C/C++ 7.0
  3959.          - Microsoft Visual C++ 1.5 Professional
  3960.          - Microsoft C/C++ for Windows NT (Beta Release 3/93)
  3961.          - Microsoft Visual C++ 1.0 for Windows NT (Beta Release 6/93)
  3962.          - Microsoft Visual C++ 1.1 for Windows NT
  3963.          - Microsoft Visual C++ 2.2
  3964.          - Microsoft Visual C++ 4.0
  3965.          - Microsoft Visual C++ 4.1
  3966.          - Microsoft Visual C++ 4.2
  3967.          - Microsoft C for SCO UNIX System V Rel. 3.2
  3968.          - Microsoft Macro Assembler MASM 5.1
  3969.          - Borland Turbo C++ 1.0
  3970.          - Borland C++ 2.0
  3971.          - Borland C++ 3.1
  3972.          - Borland C++ 1.0 for OS/2
  3973.          - Borland Turbo Assembler TASM 2.0
  3974.          - Intel 80860 Metaware High C i860 APX (UNIX-hosted)
  3975.          - Intel 80960 C-Compiler (ic960, ec960)
  3976.          - Intel 80960 Assembler (asm960)
  3977.          - Watcom C/C++ 10.0a
  3978.          - GNU-960 Tools (UNIX-hosted)
  3979.          - GNU-C Compiler 2.2.2 / 2.4.5 / 2.5.7 / 2.6.3 / 2.7.0 (C, C++,
  3980.            Objective-C), GNU-C DOS and OS/2 ports (DJGPP, EMX)
  3981.          - GNU Assembler
  3982.          - AT&T C++ 2.1 CFRONT (C++ to C translator) for SCO UNIX System
  3983.            V Rel. 3.2
  3984.          - IBM C-Compilers  (CC, XLC) for IBM RS 6000 RISC stations, AIX
  3985.            3.15
  3986.          - HP  C-Compilers (CC, C89)  for HP Apollo  9000 RISC stations,
  3987.            HP-UX 9.0
  3988.          - SUN SunOS 4.1 C-Compiler
  3989.          - Digital Equipment Corporation (DEC) VAX C
  3990.          - Digital Equipment Corporation (DEC) VAX FORTRAN
  3991.          - Ashton Tate dBase III plus
  3992.  
  3993.  
  3994.  
  3995.  
  3996.  
  3997.  
  3998.  
  3999.  
  4000.  
  4001.  
  4002.  
  4003.  
  4004.  
  4005.                                         64
  4006.  
  4007.  
  4008.  
  4009.          8.7 TRADEMARKS
  4010.  
  4011.          All  brand or product  names are trademarks  (TM) or registered
  4012.          trademarks (R) of their respective owners.
  4013.  
  4014.          The  following  products and  names are  Copyright  (C) Juergen
  4015.          Mueller (J.M.), all rights reserved world-wide:
  4016.  
  4017.               CXT (TM) C EXPLORATION TOOLS
  4018.               CFT (TM) C FUNCTION TREE GENERATOR
  4019.               CFTN (TM) C FUNCTION TREE NAVIGATOR
  4020.               CST (TM) C STRUCTURE TREE GENERATOR
  4021.               CSTN (TM) C STRUCTURE TREE NAVIGATOR
  4022.  
  4023.               CXTWIN (TM) C EXPLORATION TOOLS for Windows
  4024.               CFTWIN (TM) C FUNCTION TREE GENERATOR for Windows
  4025.               CSTWIN (TM) C STRUCTURE TREE GENERATOR for Windows
  4026.  
  4027.               DXT (TM) DBASE EXPLORATION TOOLS
  4028.               DFT (TM) DBASE FUNCTION TREE GENERATOR
  4029.               DFTN (TM) DBASE FUNCTION TREE NAVIGATOR
  4030.  
  4031.               DXTWIN (TM) DBASE EXPLORATION TOOLS for Windows
  4032.               DFTWIN (TM) DBASE FUNCTION TREE GENERATOR for Windows
  4033.  
  4034.               FXT (TM) FORTRAN EXPLORATION TOOLS
  4035.               FFT (TM) FORTRAN FUNCTION TREE GENERATOR
  4036.               FFTN (TM) FORTRAN FUNCTION TREE NAVIGATOR
  4037.  
  4038.               FXTWIN (TM) FORTRAN EXPLORATION TOOLS for Windows
  4039.               FFTWIN (TM) FORTRAN FUNCTION TREE GENERATOR for Windows
  4040.  
  4041.               LXT (TM) LISP EXPLORATION TOOLS
  4042.               LFT (TM) LISP FUNCTION TREE GENERATOR
  4043.               LFTN (TM) LISP FUNCTION TREE NAVIGATOR
  4044.  
  4045.               LXTWIN (TM) LISP EXPLORATION TOOLS for Windows
  4046.               LFTWIN (TM) LISP FUNCTION TREE GENERATOR for Windows
  4047.  
  4048.          These packages are part of
  4049.  
  4050.               SXT (TM) SOFTWARE EXPLORATION TOOLS
  4051.               SXTWIN (TM) SOFTWARE EXPLORATION TOOLS for Windows
  4052.  
  4053.          which  provide a similar set of  functionalities for the source
  4054.          code analysis of different programming languages.
  4055.  
  4056.          See PRODUCT.DOC for a complete overview of the SXT packages and
  4057.          the different supported platforms.
  4058.  
  4059.  
  4060.  
  4061.  
  4062.  
  4063.  
  4064.  
  4065.  
  4066.  
  4067.  
  4068.                                         65
  4069.  
  4070.  
  4071.  
  4072.          9   APPENDIX
  4073.  
  4074.          9.1 APPENDIX 1: C/C++ PRECOMPILER DEFINES
  4075.  
  4076.          The  following list shows the  built-in precompiler defines for
  4077.          the  supported  compiler  types (option  -T).  It  contains the
  4078.          default defines  and the optional memory model and architecture
  4079.          defines.
  4080.  
  4081.          Other  default compiler defines  which are  usually declared by
  4082.          some  of the compilers are not automatically  defined by the -T
  4083.          option.  These   are  defines  for  compilation  like  WINDOWS,
  4084.          __WINDOWS__,  _Windows, DLL  or __DLL__, for  optimization like
  4085.          __OPTIMIZE__ or __FASTCALL__ or others like those about target-
  4086.          (operating-) systems like NT, MIPS, UNIX, unix, __unix__, i386,
  4087.          __i386__, GNUDOS,  BSD, VMS, USG, DGUX or hpux. Other sometimes
  4088.          predefined  macros are __STRICT_ANSI__ or __CHAR_UNSIGNED__. If
  4089.          necessary,  they can be user  defined on the  command line with
  4090.          the -D option.
  4091.  
  4092.          The macro  name __cplusplus will be defined if the command line
  4093.          option '-C++' is set to enable C++ processing.
  4094.  
  4095.          MSC51 (Microsoft C 5.1):
  4096.          Default defines:        MSDOS, M_I86
  4097.          C++ specific defines:   (none)
  4098.          Memory model defines:   M_I86SM, M_I86MM, M_I86CM, M_I86LM,
  4099.                                  M_I86HM
  4100.  
  4101.          MSC70 (Microsoft C/C++ 7.0):
  4102.          Default defines:        MSDOS, M_I86, _MSC_VER (= 700)
  4103.          C++ specific defines:   (none)
  4104.          Memory model defines:   M_I86TM, M_I86SM, M_I86MM, M_I86CM,
  4105.                                  M_I86LM, M_I86HM
  4106.  
  4107.          MSVC15 (Microsoft Visual C++ 1.5):
  4108.          Default defines:        MSDOS, M_I86, _MSC_VER (= 800)
  4109.          C++ specific defines:   (none)
  4110.          Memory model defines:   M_I86TM, M_I86SM, M_I86MM, M_I86CM,
  4111.                                  M_I86LM, M_I86HM
  4112.  
  4113.          MSVC22 (Microsoft Visual C++ 2.2):
  4114.          Default defines:        _MSC_VER (= 900), _M_IX86 (= 400),
  4115.                                  _WIN32
  4116.          C++ specific defines:   (none)
  4117.          Memory model defines:   (not necessary)
  4118.  
  4119.          MSVC40 (Microsoft Visual C++ 4.0):
  4120.          Default defines:        _MSC_VER (= 1000), _M_IX86 (= 400),
  4121.                                  _WIN32
  4122.          C++ specific defines:   (none)
  4123.          Memory model defines:   (not necessary)
  4124.  
  4125.          MSVC41 (Microsoft Visual C++ 4.1):
  4126.          Default defines:        _MSC_VER (= 1010), _M_IX86 (= 400),
  4127.                                  _WIN32
  4128.          C++ specific defines:   (none)
  4129.          Memory model defines:   (not necessary)
  4130.  
  4131.                                         66
  4132.  
  4133.  
  4134.  
  4135.  
  4136.          MSVC42 (Microsoft Visual C++ 4.2):
  4137.          Default defines:        _MSC_VER (= 1020), _M_IX86 (= 400),
  4138.                                  _WIN32, _MFC_VER (= 0x0420)
  4139.          C++ specific defines:   (none)
  4140.          Memory model defines:   (not necessary)
  4141.  
  4142.          TC10 (Borland Turbo C++ 1.0):
  4143.          Default defines: _      MSDOS__, __TURBOC__
  4144.          C++ specific defines:   __TCPLUSPLUS
  4145.          Memory model defines:   __TINY__, __SMALL__, __MEDIUM__,
  4146.                                  __COMPACT_, __LARGE__, __HUGE__
  4147.  
  4148.          BC20 (Borland C++ 2.0):
  4149.          Default defines:        __MSDOS__, __BORLANDC__ (= 0x0200),
  4150.                                  __TURBOC__ (= 0x0297)
  4151.          C++ specific defines:   __BCPLUSPLUS__ (= 0x0200),
  4152.                                  __TCPLUSPLUS__ (= 0x0200)
  4153.          Memory model defines:   __TINY__, __SMALL__, __MEDIUM__,
  4154.                                  __COMPACT_, __LARGE__, __HUGE__
  4155.  
  4156.          BC31 (Borland C++ 3.1):
  4157.          Default defines:        __MSDOS__, __BORLANDC__ (= 0x0410),
  4158.                                  __TURBOC__ (= 0x0410)
  4159.          C++ specific defines:   __BCPLUSPLUS__ (= 0x0310),
  4160.                                  __TCPLUSPLUS__ (= 0x0310)
  4161.          Memory model defines:   __TINY__, __SMALL__, __MEDIUM__,
  4162.                                  __COMPACT_, __LARGE__, __HUGE__
  4163.  
  4164.          BC10OS2 (Borland C++ 1.0 for OS/2):
  4165.          Default defines:        __OS2__, __BORLANDC__ (= 0x0400),
  4166.                                  __TURBOC__ (= 0x0400)
  4167.          C++ specific defines:   __BCPLUSPLUS__ (= 0x0320),
  4168.                                  __TCPLUSPLUS__ (= 0x0320),
  4169.                                  __TEMPLATES__
  4170.          Memory model defines:   (not necessary)
  4171.  
  4172.          WATCOMC100 (Watcom C/C++ 10.0):
  4173.          Default defines:        __WATCOMC__ (= 1000)
  4174.          C++ specific defines:   __WATCOM_CPLUSPLUS__ (= 1000)
  4175.          Memory model defines:   (cannot be specified, too many targets)
  4176.  
  4177.          GNUC222 (GNU C 2.2.2):
  4178.          Default defines:        __GNUC__ (= 2), __GNUC_MINOR__ (= 2)
  4179.                                  __VERSION__ (= "2.2.2")
  4180.          C++ specific defines:   __GNUG__
  4181.          Memory model defines:   (not necessary)
  4182.  
  4183.          GNUC263 (GNU C 2.6.3):
  4184.          Default defines:        __GNUC__ (= 2), __GNUC_MINOR__ (= 6),
  4185.                                  __VERSION__ (= "2.6.3")
  4186.          C++ specific defines:   __GNUG__
  4187.          Memory model defines:   (not necessary)
  4188.  
  4189.          GNUC272 (GNU C 2.7.2):
  4190.          Default defines:        __GNUC__ (= 2), __GNUC_MINOR__ (= 7),
  4191.                                  __VERSION__ (= "2.7.2")
  4192.          C++ specific defines:   __GNUG__
  4193.  
  4194.                                         67
  4195.  
  4196.  
  4197.  
  4198.          Memory model defines:   (not necessary)
  4199.  
  4200.          I960 (Intel iC960 3.0):
  4201.          Default defines:         __i960
  4202.          C++ specific defines:   (none)
  4203.          Memory model defines:   (not necessary)
  4204.          Architecture defines:   __i960KA, __i960KB, __i960SA, __i960SB,
  4205.                                  __i960MC, __i960CA
  4206.  
  4207.  
  4208.          USER DEFINED ADAPTATION OF CFT AND CST TO PREVIOUSLY LISTED AND
  4209.          OTHER COMPILERS NOT SUPPORTED BY OPTION -T
  4210.  
  4211.          The  adaptation of CFT and  CST to C/C++ compilers  can be done
  4212.          with  the -D,  -U and -B  options. First  you have  to find out
  4213.          which  precompiler  defines  the compiler  uses  by  default or
  4214.          related to  command line options. For these information see the
  4215.          documentation  and help-files for your  compiler. The necessary
  4216.          precompiler  defines have to be specified for  CFT and CST with
  4217.          -D. Additionally  it may be necessary to specify undefines with
  4218.          -U  and to declare the  basic type size with  -B. The following
  4219.          line  shows  as an  example the  necessary options  for  the MS
  4220.          Visual C++ 1.5 compiler (large model):
  4221.  
  4222.            -DMSDOS -DM_I86 -D_MSC_VER=800 -DM_I86LM
  4223.            -B0,1,2,2,4,4,8,10*4,4
  4224.  
  4225.  
  4226.          9.2 APPENDIX 2: RESERVED C/C++ KEYWORDS
  4227.  
  4228.          The  following list shows the keywords  being recognized by CFT
  4229.          and CST, the standard C keywords, the C++ keywords and the non-
  4230.          standard  keywords which  are compiler dependent  extensions to
  4231.          the  C  or  C++ language.  Standard  C  keywords  are  also C++
  4232.          keywords,  always!  The  C++ keywords  are  recognized  only if
  4233.          option   '-C++'  is   set,  otherwise   they  are   treated  as
  4234.          identifiers.  This list may not  be complete or  correct due to
  4235.          changes  or upcoming  new releases  of the  supported compilers
  4236.          with  new extensions  or extensions  to the  language standard.
  4237.          Vendor  or compiler specific extensions to  the languages as in
  4238.          GNU   C  (e.g.  __alignof,   __classof,  interface,  signature,
  4239.          __FUNCTION__, ...) or undocumented features are ignored.
  4240.  
  4241.          Standard  C  keywords:  asm, auto,  break,  case,  char, const,
  4242.          continue,  default, do, else,  enum, extern,  float, for, goto,
  4243.          if, int, long, register, return, short, signed, sizeof, static,
  4244.          struct, switch, typedef, union, unsigned, void, volatile, while
  4245.  
  4246.          Standard C++ keywords: and, and_eq, bitand, bitor, bool, catch,
  4247.          class,  const_cast,  delete,  double,  dynamic_cast,  explicit,
  4248.          false,  friend, inline,  mutable, namespace, new,  not, not_eq,
  4249.          operator,    or,    or_eq,    private,    protected,    public,
  4250.          reinterpret_cast,  static_cast,  template,  this,  throw, true,
  4251.          try, typeid, typename, using, virtual, wchar_t, xor, xor_eq
  4252.  
  4253.          Following  are some vendor specific  C and C++  keywords. It is
  4254.          not  known  whether  all of  them  are  still  valid  in actual
  4255.          versions.
  4256.  
  4257.                                         68
  4258.  
  4259.  
  4260.  
  4261.  
  4262.          Vendor  specific C  keywords (Microsoft, Borland):  cdecl, far,
  4263.          fortran,   huge,  interrupt,  near,   pascal,  __asm,  __based,
  4264.          __cdecl,   __const,   __emit,   __export,   __far,  __fastcall,
  4265.          __finally,  __fortran,  __huge, __interrupt,  __loadds, __near,
  4266.          __saveregs,  __segment, __segname, __self, __signed, __stdcall,
  4267.          __syscall,  __try,  __volatile,  _asm,  _based,  _cdecl, _emit,
  4268.          _export, _far, _fastcall, _fortran, _huge, _interrupt, _loadds,
  4269.          _near, _pascal, _saveregs, _seg, _segment, _segname, _self
  4270.  
  4271.          Vendor specific C++ keywords (Microsoft, Borland, GNU):
  4272.          classof,   dynamic,   except,   exception,   overload,  typeof,
  4273.          __alignof,  __alignof__,  __asm__,  __attribute, __attribute__,
  4274.          __classof,  __classof__,  __const__,  __except,  __extension__,
  4275.          __headof,    __headof__,   __inline,   __inline__,   __label__,
  4276.          __signed__, __typeof, __typeof__, __volatile__
  4277.  
  4278.  
  4279.          9.3 APPENDIX 3: RESERVED FORTRAN KEYWORDS
  4280.  
  4281.          The  following lists show the  keywords and intrinsic functions
  4282.          from  FORTRAN 77  and non-standard  extensions (VAX,  CDC, AIX,
  4283.          UNIX, ...)  recognized by FFT. This list may not be complete or
  4284.          correct.
  4285.  
  4286.          Keywords  (standard  & non-standard):  ACCEPT,  ASSERT, ASSIGN,
  4287.          AUTOMATIC,  BACKSPACE,  BLOCKDATA,  BLOCK,  BYTE,  CALL,  CASE,
  4288.          CHARACTER,  CLOSE,  COMMON,  COMPLEX,  CONTINUE,  DATA, DELETE,
  4289.          DICTIONARY,  DIMENSION, DOUBLECOMPLEX, DOUBLEPRECISION, DOUBLE,
  4290.          DOWHILE,  DO,  ELSEIF,  ELSE,  ENDDO,  ENDFILE, ENDIF,  ENDMAP,
  4291.          ENDSELECT,   ENDSTRUCTURE,  ENDUNION,   ENDWHILE,  END,  ENTRY,
  4292.          EQUIVALENCE,  EXTERNAL, FILE,  FORMAT, FUNCTION, GOTO,  GO, IF,
  4293.          IMPLICITNONE,  IMPLICIT, INCLUDE,  INQUIRE, INTEGER, INTRINSIC,
  4294.          LOGICAL,  NAMELIST,  NONE,  OPEN,  PARAMETER,  PAUSE,  POINTER,
  4295.          PRECISION,  PRINT, PROGRAM, PUNCH, READ,  REAL, RECORD, RETURN,
  4296.          REWIND,   REWRITE,  SAVE,  SELECT,  SELECTCASE,  STATIC,  STOP,
  4297.          STRUCTURE, SUBROUTINE, THEN, TO, TYPE, UNION, UNLOCK, VOLATILE,
  4298.          WHILE, WRITE, $INCLUDE
  4299.  
  4300.          Intrinsic  functions: ABS,  ACHAR,  ACOS, AIMAG,  AINT, ALOG10,
  4301.          ALOG,  AMAX0,  AMAX1,  AMIN0, AMIN1,  AMOD,  AND,  ANINT, ASIN,
  4302.          ATAN2, ATAN,  CABS, CCOS, CEXP, CHAR, CLOG, CMPLX, CONJG, COSH,
  4303.          COS,  CSIN,  CSQRT, DABS,  DACOS, DASIN,  DATAN2,  DATAN, DBLE,
  4304.          DCMPLX,  DCONJG, DCOSH, DCOS,  DDIM, DEXP,  DFLOAT, DIMAG, DIM,
  4305.          DINT,  DLOG10, DLOG, DMAX1,  DMIN1, DMOD,  DNINT, DPROD, DSIGN,
  4306.          DSINH,  DSIN,  DSQRT,  DTANH,  DTAN,  EPBASE,  EPEMAX,  EPEMIN,
  4307.          EPHUGE,  EPMRSP, EPPREC,  EPTINY,  EXP, FLOAT,  FPABSP, FPEXPN,
  4308.          FPFRAC,  FPMAKE,  FPRRSP, FPSCAL,  IABS,  IACHAR,  ICHAR, IDIM,
  4309.          IDINT,  IDNINT, IFIX, IMAG,  INDEX, INT, ISIGN,  LEN, LGE, LGT,
  4310.          LLE, LLT, LOG10, LOG, LSHIFT, MAX0, MAX1, MAX, MIN0, MIN1, MIN,
  4311.          MOD, NINT,  NOT, OR, REAL, RSHIFT, SIGN, SINH, SIN, SNGL, SQRT,
  4312.          TANH, TAN, XOR, ZABS, ZCOS, ZEXP, ZLOG, ZSIN, ZSQRT,
  4313.  
  4314.          Non-standard  intrinsic functions: ABORT, ACOSD, ASIND, ATAN2D,
  4315.          ATAND, BTEST,  CABS1, CAMAX, CAMIN, CASUM, CAXPY, CCOPY, CDABS,
  4316.          CDCOS,  CDEXP, CDLOG, CDOTC, CDOTU,  CDSIN, CDSQRT, CMAX, CMIN,
  4317.          CNORM2,  CNRM2, CNRSQ, COSD, CROTG,  CROT, CSCAL, CSET, CSIGN1,
  4318.          CSIGN,  CSUM, CSWAP, CVCAL, CZAXPY,  DAMAX, DAMIN, DASUM, DATE,
  4319.  
  4320.                                         69
  4321.  
  4322.  
  4323.  
  4324.          DAXPY,  DCOPY, DDOT, DMAX,  DMIN, DNORM2,  DNRM2, DNRSQ, DREAL,
  4325.          DROTG,  DROT, DSCAL, DSET, DSUM,  DSWAP, DVCAL, DZAXPY, ERRSNS,
  4326.          EXIT,  GETARG, GETENV,  GMTIME, HFIX,  I, IARGC,  IAND, IBCHNG,
  4327.          IBCLR,  IBITS,  IBSET, ICAMAX,  ICAMIN,  ICMAX,  ICMIN, IDAMAX,
  4328.          IDAMIN,  IDATE, IDMAX, IDMIN, IEOR,  IOR, IQINT, IQNINT, IRAND,
  4329.          ISAMAX,  ISAMIN,  ISHA,  ISHC,  ISHFT,  ISHFTC,  ISMAX,  ISMIN,
  4330.          IZAMAX,  IZAMIN, IZMAX,  IZMIN, JFIX, LTIME,  MVBITS, NWORKERS,
  4331.          QEXT,  QFLOAT, RAN,  RAND, SAMAX,  SAMIN, SASUM,  SAXPY, SCOPY,
  4332.          SDOT,  SECNDS, SIND, SIZEOF, SMAX,  SMIN, SNORM2, SNRM2, SNRSQ,
  4333.          SRAND,  SROTG, SROT, SSCAL,  SSET, SSUM,  SSWAP, SVCAL, SYSTEM,
  4334.          SZAXPY,  TAND, TIME, ZAMAX, ZAMIN,  ZASUM, ZAXPY, ZCOPY, ZDOTC,
  4335.          ZDOTU,  ZEXT, ZMAX,  ZMIN, ZNORM2,  ZNRM2, ZNRSQ,  ZROTG, ZROT,
  4336.          ZSCAL, ZSET, ZSUM, ZSWAP, ZVCAL, ZZAXPY
  4337.  
  4338.          VAX specific built-in functions: %DESCR, %LOC, %REF, %VAL
  4339.  
  4340.  
  4341.          9.4 APPENDIX 4: EFFICIENCY
  4342.  
  4343.          To  provide some values about  the speed and  the efficiency of
  4344.          the programs, tests were performed with CFT386 and CST386.
  4345.  
  4346.          One  test with CFT386 (v2.21) was done  with the source code of
  4347.          the  C++ part of the  GNU-C compiler (version  2.2.2), which is
  4348.          the largest  of the three compiler parts (C, C++, Objective-C).
  4349.          The test was made on a 33 MHz 80486, 8 MB RAM, 256 KB cache, 12
  4350.          ms hard disk, 2.5 MB RAM-disk. The command line options were -m
  4351.          -rauspPC_INCLUDE_PATH -TGNU  -cs -Cs -n -W5 -G -vn:\ -L+ -time.
  4352.          The following results have been found:
  4353.  
  4354.          - 137  files (71 source files  and 66 include  files) have been
  4355.            scanned
  4356.          - a  total number of 2318  functions has been  found from which
  4357.            2236 functions were defined in the 69 source files
  4358.          - the  directed  call graph  would  have 2302  nodes  and 10276
  4359.            connections
  4360.          - the  critical function call path has  a maximum nesting level
  4361.            of 115
  4362.          - the total size of the 137 files is 6.538 MB with 208900 lines
  4363.            (about  31 bytes/line),  source  code/file size  ratio 0.712,
  4364.            average function size is 1956 bytes resp. 63 lines
  4365.          - the  effective size  of the  preprocessed and  scanned source
  4366.            code  (source files  and their included  files) is  20.990 MB
  4367.            with 602300 lines - the resulting output file has about 3.921
  4368.            MB and 36000 lines
  4369.          - the resulting  6 database files have a size of 870 KB (source
  4370.            code/database ratio is about 7.5 : 1)
  4371.          - inside  BRIEF,  a  database  search  for  the  location of  a
  4372.            function is performed in less than 4 seconds
  4373.          - the  total  time  for  the  complete  processing was  21'57''
  4374.            minutes  (11'03''  for preprocessing,  8'13''  for analyzing,
  4375.            1'00'' for output file writing, 1'32'' for database writing)
  4376.          - the  average  speed  for this  source  code  was  about 1.080
  4377.            MB/min. respectively 31000 lines/min.
  4378.  
  4379.          Another  test  with  CFT386  (v2.21)  was  done  with  a  large
  4380.          commercial  project. The test was made on  a 33 MHz 80486, 8 MB
  4381.          RAM,  256 KB cache, 12  ms hard disk, no  RAM-disk. The command
  4382.  
  4383.                                         70
  4384.  
  4385.  
  4386.  
  4387.          line  options were -m+ -rausp  -cs -Cs -n -time  -cmdline -M -G
  4388.          -TMSC70,L -P -L -W5. The results:
  4389.  
  4390.          - 291  files (194 source files and 97  include files) have been
  4391.            scanned
  4392.          - a  total number of 1955  functions has been  found from which
  4393.            1866 functions were defined in the source files
  4394.          - the  total size  of the 291  files is  15.719 MB  with 387600
  4395.            lines,  source code/file  size ratio 0.531,  average function
  4396.            size is 2800 bytes resp. 100 lines
  4397.          - the  effective size  of the  preprocessed and  scanned source
  4398.            code  (source files and  their included files)  is 220.685 MB
  4399.            with 2861000 lines
  4400.          - the  total  time  for the  complete  processing  was 161'02''
  4401.            minutes  (139'43'' for preprocessing,  19'21'' for analyzing,
  4402.            0'56'' for output file writing, 0'58'' for database writing)
  4403.          - the  average  speed  for this  source  code  was  about 1.388
  4404.            MB/min. respectively 17990 lines/min.
  4405.  
  4406.          To  get some efficiency values for  CST386 (v2.21), the include
  4407.          files  from another commercial  project were  analyzed for data
  4408.          types.  The test was made on a  33 MHz 80486, 8  MB RAM, 256 KB
  4409.          cache, 12 ms hard disk, no RAM-disk:
  4410.  
  4411.          - 52 include files have been scanned
  4412.          - a  total number of 605 data types  have been found from which
  4413.            567  structures/unions were defined  in 42 of  the 54 include
  4414.            files
  4415.          - the  directed  call  graph  would  have  588  nodes and  1787
  4416.            connections
  4417.          - the  total size of the 52 files  is 1.384 MB with 25410 lines
  4418.            (about 54 bytes/line), source code/file size ratio 0.342
  4419.          - the  resulting output  file (options  -rasp  -cs -Cs  -n) has
  4420.            about 378 KB and 8760 lines
  4421.          - the resulting  6 database files have a size of 315 KB (source
  4422.            code/database ratio is about 4.4 : 1)
  4423.          - the total time for the complete processing was 0'43'' minutes
  4424.            (0'17''  for  analysis, 0'05''  for output  file  writing and
  4425.            0'20'' for database writing)
  4426.          - the  average  speed  for this  source  code  was  about 4.885
  4427.            MB/min.  respectively  89700  lines/min  (only  analysis,  no
  4428.            preprocessing performed).
  4429.  
  4430.          Another  test with CST386 (v2.21) was done  with the C++ source
  4431.          code of  the Microsoft Foundation Class (MFC) 2.0. The test was
  4432.          made  on a 33  MHz 80486, 8  MB RAM, 256  KB cache,  12 ms hard
  4433.          disk,  2.5 MB  RAM-disk. The  command  line options  were -rasp
  4434.          -I\msvc\mfc\include    -I\msvc\include   -P    -TMSVCWNT   -C++
  4435.          -D_WINDOWS  -D_X86_  -Cs -n  -b  -W5 -time  -G  -vn:\  -L+. The
  4436.          following results have been found:
  4437.  
  4438.          - 170  files (95 source files  and 75 include  files) have been
  4439.            scanned
  4440.          - a  total number of 890 data types  have been found from which
  4441.            701 were defined in the source and include files
  4442.          - the  directed  call  graph  would  have  755  nodes and  1402
  4443.            connections
  4444.  
  4445.  
  4446.                                         71
  4447.  
  4448.  
  4449.  
  4450.          - the  total size of the 170 files  is 2.42 MB with 87500 lines
  4451.            (about 28 bytes/line), source code/file size ratio 0.779
  4452.          - the  effective size  of the  preprocessed and  scanned source
  4453.            code  (source files  and their included  files) is  157.28 MB
  4454.            with 5580100 lines
  4455.          - the  total  time  for the  complete  processing  was 106'20''
  4456.            minutes  (72'07''  for preprocessing,  33'14''  for analysis,
  4457.            0'12'' for output file writing, 0'44'' for database writing)
  4458.          - the average speed for this source code was about 1.49 MB/min.
  4459.            respectively 53000 lines/min.
  4460.  
  4461.          The calculated average values for the analysis speed differ due
  4462.          to  the effective size of  the 'really' present  source code in
  4463.          relation  to the size of the comments  which can be seen by the
  4464.          code/file size ratio. The speed values do not consider that, if
  4465.          the  preprocessing option -P is  set, the source  code is first
  4466.          preprocessed to  a temporary file and then analyzed in a second
  4467.          step  so that  large parts of  the source  code are  read twice
  4468.          (original and preprocessed code) and written once (intermediate
  4469.          preprocessor output).
  4470.  
  4471.          With  these facts in  mind, the analysis  speed of  CFT and CST
  4472.          seems to be quite acceptable!
  4473.  
  4474.  
  4475.          9.5 APPENDIX 5: SYSTEM REQUIREMENTS
  4476.  
  4477.          DOS real mode versions:
  4478.          - IBM-AT or  100% compatible with Intel 80286 or higher, 640 KB
  4479.            RAM, hard-disk, MS-DOS 5.0 or higher
  4480.  
  4481.          DOS protected mode versions:
  4482.          - IBM-AT or 100% compatible with Intel 80386+80387 or higher, 4
  4483.            MB  RAM (8 MB  recommended), hard-disk, MS-DOS  5.0 or higher
  4484.            (NOTE:  it  is  currently not  known  if  the  protected mode
  4485.            version will run with Windows 95 (MS-DOS 7.0))
  4486.  
  4487.          Windows 16 bit versions:
  4488.          - IBM-AT  or 100% compatible with  Intel 80386 or  higher, 4 MB
  4489.            RAM  (8  MB recommended),  hard-disk, MS-DOS  5.0  or higher,
  4490.            Windows  3.1 or Windows for  Workgroups 3.11 (enhanced mode),
  4491.            VB40016.DLL  (Visual  Basic  4.0  16-bit    Run-Time  library
  4492.            installed  in the \windows\system directory,  required by the
  4493.            DLL sample application SXTNVIEW)
  4494.  
  4495.          Windows 32 bit (Win32s) versions:
  4496.          - IBM-AT  or 100% compatible with  Intel 80386 or  higher, 8 MB
  4497.            RAM,  hard-disk, Windows NT 3.51, Windows  95, Windows 3.1 or
  4498.            Windows for Workgroups 3.11 and Win32s subsystem (v1.30c)
  4499.  
  4500.  
  4501.          9.6 APPENDIX 6: INSTALLATION
  4502.  
  4503.          See  the  appropriate documentation  (INSTALL.DOC, INSTALL.W32,
  4504.          PROBLEMS.DOC,  ...) for  information about the  installation of
  4505.          the SXT programs.
  4506.  
  4507.  
  4508.  
  4509.                                         72
  4510.  
  4511.  
  4512.  
  4513.          9.7 APPENDIX 7: SXT REVIEWS
  4514.  
  4515.          - The C Users Journal (Volume 12, Number 1, January 1994) (CXT)
  4516.  
  4517.          - The C/C++ Users Journal (Volume 12, Number 12, December 1995)
  4518.            (CXT, CXTWIN)
  4519.  
  4520.          - Professionelle Shareware 1/1993 (Computer Solutions Software
  4521.            GmbH) (CXT)
  4522.  
  4523.          - Professionelle Shareware 3/1994 (Computer Solutions Software
  4524.            GmbH) (DXT, FXT, LXT)
  4525.  
  4526.          - Shareware Professionell 11/1994 (Computer Solutions Software
  4527.            GmbH) (CXTWIN, DXTWIN, FXTWIN, LXTWIN)
  4528.  
  4529.  
  4530.          9.8 APPENDIX 8: AVAILABILITY
  4531.  
  4532.          The SHAREWARE versions of the SXT programs can be obtained from
  4533.          various shareware  vendors, accessed and downloaded via WWW and
  4534.          FTP  from many Internet sites  and mailboxes and  found on many
  4535.          CD-ROM shareware collections.
  4536.  
  4537.          The  following list  is not complete,  only the  known vendors,
  4538.          WWW- and FTP-sites (usually primary sites where the software is
  4539.          uploaded by  the author or which are known to be up-to-date) or
  4540.          CD-ROM's are shown.
  4541.  
  4542.  
  4543.          VENDORS:
  4544.  
  4545.          - Computer Solutions Software (CSL) GmbH, Postfach 1180,
  4546.            D-85561 Grafing, GERMANY
  4547.  
  4548.          - PEARL Agency, Am Kalischacht 4, D-79426 Buggingen, GERMANY
  4549.  
  4550.          - The C-Users' Group (CUG), 1601 W. 23rd St., Suite 200,
  4551.            Lawrence, KS 66046, U.S.A. (CXT: CUG Library Disk # 391)
  4552.  
  4553.          - EMS Professional Software, 4505 Buckhurst Ct., Olney, MD
  4554.            20832-1830, U.S.A.
  4555.  
  4556.          - Ziff-Davies Interactive, The Riverview Building, One
  4557.            Athenaeum Street, Cambridge, MA 02142, U.S.A. (distribution
  4558.            on CD-ROM or electronically through Public Brand Software,
  4559.            ZiffNet on CompuServe, ZiffNet on Prodigy, and Interchange)
  4560.  
  4561.          - Limelight Media Inc., P.O. Box 3536, Terre Haute, IN 47803,
  4562.            U.S.A. (Platinum Shareware CD-ROM Series)
  4563.  
  4564.          - AMUG CD, Inc., 4131 N. 24th Street #A-120, Phoenix, AZ 85016,
  4565.            U.S.A.
  4566.  
  4567.  
  4568.  
  4569.  
  4570.  
  4571.  
  4572.                                         73
  4573.  
  4574.  
  4575.  
  4576.          WWW / FTP:
  4577.  
  4578.          - SIMTEL:
  4579.            WWW: http://www.simtel.net/simtel.net
  4580.            FTP: ftp.simtel.net
  4581.            (directories: CXT: msdos/c, DXT: msdos/dbase,
  4582.            FXT: msdos/fortran, LXT: msdos/misclang, CXTWIN/ FXTWIN/
  4583.            LXTWIN: win3/pgmtools, DXTWIN: win3/database)
  4584.  
  4585.          - WINSITE (previously known as CICA):
  4586.            WWW: http://www.winsite.com
  4587.            FTP: ftp.winsite.com
  4588.  
  4589.          - GARBO:
  4590.            WWW: http://garbo.uwasa.fi
  4591.            FTP: garbo.uwasa.fi
  4592.            (directories: CXT: pc/c-lang, DXT/FXT/LXT: pc/programming,
  4593.            SXT Windows versions: /windows/programming)
  4594.  
  4595.          - JUMBO:
  4596.            WWW: http://www.jumbo.com
  4597.  
  4598.          - Shareware:
  4599.            WWW: http://www.shareware.com
  4600.  
  4601.          - Sharestuff:
  4602.            WWW: http://www.sharestuff.com
  4603.  
  4604.          - Coast to Coast Telecommunication:
  4605.            WWW: http://www.coast.net
  4606.            FTP: ftp.coast.net
  4607.  
  4608.          - ZDNet (Ziff Davies):
  4609.            WWW: http://www.zdnet.com
  4610.            (CFT: rating ***, most relevant)
  4611.  
  4612.  
  4613.          CD-ROM:
  4614.  
  4615.          - The C-Users' Group (CUG) Library on CD-ROM
  4616.            (The C-Users' Group (CUG), 1601 W. 23rd St., Suite 200,
  4617.            Lawrence, KS 66046, U.S.A.)
  4618.  
  4619.          - CSL-MEGA CD Vol. 6, Vol. 7, Vol. 9
  4620.            (Computer Solutions Software (CSL) GmbH, Postfach 1180,
  4621.            D-85561 Grafing, GERMANY)
  4622.  
  4623.          There  are  also  CD-ROM's  available  containing the  complete
  4624.          collection of  files from the SIMTEL, GARBO and other FTP-sites
  4625.          which may also include some or all of the SXT programs.
  4626.  
  4627.  
  4628.          BOOKS:
  4629.  
  4630.          Several  books  are  available  or  have  been announced  which
  4631.          include SXT programs on CD-ROM's or disks:
  4632.  
  4633.          - 'Algorithmen fuer C und C++' (Addison-Wesley)
  4634.  
  4635.                                         74
  4636.  
  4637.  
  4638.  
  4639.  
  4640.          - 'Windows Programming with Shareware Tools' by Victor Volkman
  4641.            (Miller Freeman Inc., ISBN # 0-87930-434-0)
  4642.            (more information on WWW server http://www.HAL9k.com)
  4643.  
  4644.          - 'Windows 95 Secrets' (IDG Books)
  4645.  
  4646.          - 'NetWarriors in C++: Programming 3D Windows Games' (John
  4647.            Wiley & Sons, Inc.).
  4648.  
  4649.  
  4650.  
  4651.  
  4652.  
  4653.  
  4654.  
  4655.  
  4656.  
  4657.  
  4658.  
  4659.  
  4660.  
  4661.  
  4662.  
  4663.  
  4664.  
  4665.  
  4666.  
  4667.  
  4668.  
  4669.  
  4670.  
  4671.  
  4672.  
  4673.  
  4674.  
  4675.  
  4676.  
  4677.  
  4678.  
  4679.  
  4680.  
  4681.  
  4682.  
  4683.  
  4684.  
  4685.  
  4686.  
  4687.  
  4688.  
  4689.  
  4690.  
  4691.  
  4692.  
  4693.  
  4694.  
  4695.  
  4696.  
  4697.  
  4698.                                         75